# This file was auto-generated by Fern from our API Definition.

import typing

import pydantic
from ..core.pydantic_utilities import IS_PYDANTIC_V2
from ..core.unchecked_base_model import UncheckedBaseModel
from .transfer_order_line import TransferOrderLine
from .transfer_order_status import TransferOrderStatus


class TransferOrder(UncheckedBaseModel):
    """
    Represents a transfer order for moving [CatalogItemVariation](entity:CatalogItemVariation)s
    between [Location](entity:Location)s. Transfer orders track the entire lifecycle of an inventory
    transfer, including:
    - What items and quantities are being moved
    - Source and destination locations
    - Current [TransferOrderStatus](entity:TransferOrderStatus)
    - Shipping information and tracking
    - Which [TeamMember](entity:TeamMember) initiated the transfer

    This object is commonly used to:
    - Track [CatalogItemVariation](entity:CatalogItemVariation) movements between [Location](entity:Location)s
    - Reconcile expected vs received quantities
    - Monitor transfer progress and shipping status
    - Audit inventory movement history
    """

    id: typing.Optional[str] = pydantic.Field(default=None)
    """
    Unique system-generated identifier for this transfer order. Use this ID for:
    - Retrieving transfer order details
    - Tracking status changes via webhooks
    - Linking transfers in external systems
    """

    source_location_id: typing.Optional[str] = pydantic.Field(default=None)
    """
    The source [Location](entity:Location) sending the [CatalogItemVariation](entity:CatalogItemVariation)s.
    This location must:
    - Be active in your Square organization
    - Have sufficient inventory for the items being transferred
    - Not be the same as the destination location
    
    This field is not updatable.
    """

    destination_location_id: typing.Optional[str] = pydantic.Field(default=None)
    """
    The destination [Location](entity:Location) receiving the [CatalogItemVariation](entity:CatalogItemVariation)s.
    This location must:
    - Be active in your Square organization
    - Not be the same as the source location
    
    This field is not updatable.
    """

    status: typing.Optional[TransferOrderStatus] = pydantic.Field(default=None)
    """
    Current [TransferOrderStatus](entity:TransferOrderStatus) indicating where the order is in its lifecycle.
    Status transitions follow this progression:
    1. [DRAFT](entity:TransferOrderStatus) -> [STARTED](entity:TransferOrderStatus) via [StartTransferOrder](api-endpoint:TransferOrders-StartTransferOrder)
    2. [STARTED](entity:TransferOrderStatus) -> [PARTIALLY_RECEIVED](entity:TransferOrderStatus) via [ReceiveTransferOrder](api-endpoint:TransferOrders-ReceiveTransferOrder)
    3. [PARTIALLY_RECEIVED](entity:TransferOrderStatus) -> [COMPLETED](entity:TransferOrderStatus) after all items received
    
    Orders can be [CANCELED](entity:TransferOrderStatus) from [STARTED](entity:TransferOrderStatus) or 
    [PARTIALLY_RECEIVED](entity:TransferOrderStatus) status.
    
    This field is read-only and reflects the current state of the transfer order, and cannot be updated directly. Use the appropriate
    endpoints (e.g. [StartPurchaseOrder](api-endpoint:TransferOrders-StartTransferOrder), to change the status.
    See [TransferOrderStatus](#type-transferorderstatus) for possible values
    """

    created_at: typing.Optional[str] = pydantic.Field(default=None)
    """
    Timestamp when the transfer order was created, in RFC 3339 format.
    Used for:
    - Auditing transfer history
    - Tracking order age
    - Reporting and analytics
    """

    updated_at: typing.Optional[str] = pydantic.Field(default=None)
    """
    Timestamp when the transfer order was last updated, in RFC 3339 format.
    Updated when:
    - Order status changes
    - Items are received
    - Notes or metadata are modified
    """

    expected_at: typing.Optional[str] = pydantic.Field(default=None)
    """
    Expected transfer completion date, in RFC 3339 format.
    Used for:
    - Planning inventory availability
    - Scheduling receiving staff
    - Monitoring transfer timeliness
    """

    completed_at: typing.Optional[str] = pydantic.Field(default=None)
    """
    Timestamp when the transfer order was completed or canceled, in RFC 3339 format (e.g. "2023-10-01T12:00:00Z").
    """

    notes: typing.Optional[str] = pydantic.Field(default=None)
    """
    Optional notes about the transfer.
    """

    tracking_number: typing.Optional[str] = pydantic.Field(default=None)
    """
    Shipment tracking number for monitoring transfer progress.
    """

    created_by_team_member_id: typing.Optional[str] = pydantic.Field(default=None)
    """
    ID of the [TeamMember](entity:TeamMember) who created this transfer order. This field is not writeable by the Connect V2 API.
    """

    line_items: typing.Optional[typing.List[TransferOrderLine]] = pydantic.Field(default=None)
    """
    List of [CatalogItemVariation](entity:CatalogItemVariation)s being transferred.
    """

    version: typing.Optional[int] = pydantic.Field(default=None)
    """
    Version for optimistic concurrency control. This is a monotonically increasing integer
    that changes whenever the transfer order is modified. Use this when calling 
    [UpdateTransferOrder](api-endpoint:TransferOrders-UpdateTransferOrder) and other endpoints to ensure you're
    not overwriting concurrent changes.
    """

    if IS_PYDANTIC_V2:
        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
    else:

        class Config:
            frozen = True
            smart_union = True
            extra = pydantic.Extra.allow
