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

import typing

from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.pagination import AsyncPager, SyncPager
from ..core.request_options import RequestOptions
from ..requests.create_transfer_order_data import CreateTransferOrderDataParams
from ..requests.transfer_order_goods_receipt import TransferOrderGoodsReceiptParams
from ..requests.transfer_order_query import TransferOrderQueryParams
from ..requests.update_transfer_order_data import UpdateTransferOrderDataParams
from ..types.cancel_transfer_order_response import CancelTransferOrderResponse
from ..types.create_transfer_order_response import CreateTransferOrderResponse
from ..types.delete_transfer_order_response import DeleteTransferOrderResponse
from ..types.receive_transfer_order_response import ReceiveTransferOrderResponse
from ..types.retrieve_transfer_order_response import RetrieveTransferOrderResponse
from ..types.search_transfer_orders_response import SearchTransferOrdersResponse
from ..types.start_transfer_order_response import StartTransferOrderResponse
from ..types.transfer_order import TransferOrder
from ..types.update_transfer_order_response import UpdateTransferOrderResponse
from .raw_client import AsyncRawTransferOrdersClient, RawTransferOrdersClient

# this is used as the default value for optional parameters
OMIT = typing.cast(typing.Any, ...)


class TransferOrdersClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawTransferOrdersClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> RawTransferOrdersClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        RawTransferOrdersClient
        """
        return self._raw_client

    def create(
        self,
        *,
        idempotency_key: str,
        transfer_order: CreateTransferOrderDataParams,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> CreateTransferOrderResponse:
        """
        Creates a new transfer order in [DRAFT](entity:TransferOrderStatus) status. A transfer order represents the intent
        to move [CatalogItemVariation](entity:CatalogItemVariation)s from one [Location](entity:Location) to another.
        The source and destination locations must be different and must belong to your Square account.

        In [DRAFT](entity:TransferOrderStatus) status, you can:
        - Add or remove items
        - Modify quantities
        - Update shipping information
        - Delete the entire order via [DeleteTransferOrder](api-endpoint:TransferOrders-DeleteTransferOrder)

        The request requires source_location_id and destination_location_id.
        Inventory levels are not affected until the order is started via
        [StartTransferOrder](api-endpoint:TransferOrders-StartTransferOrder).

        Common integration points:
        - Sync with warehouse management systems
        - Automate regular stock transfers
        - Initialize transfers from inventory optimization systems

        Creates a [transfer_order.created](webhook:transfer_order.created) webhook event.

        Parameters
        ----------
        idempotency_key : str
            A unique string that identifies this CreateTransferOrder request. Keys can be
            any valid string but must be unique for every CreateTransferOrder request.

        transfer_order : CreateTransferOrderDataParams
            The transfer order to create

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CreateTransferOrderResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.transfer_orders.create(
            idempotency_key="65cc0586-3e82-384s-b524-3885cffd52",
            transfer_order={
                "source_location_id": "EXAMPLE_SOURCE_LOCATION_ID_123",
                "destination_location_id": "EXAMPLE_DEST_LOCATION_ID_456",
                "expected_at": "2025-11-09T05:00:00Z",
                "notes": "Example transfer order for inventory redistribution between locations",
                "tracking_number": "TRACK123456789",
                "created_by_team_member_id": "EXAMPLE_TEAM_MEMBER_ID_789",
                "line_items": [
                    {
                        "item_variation_id": "EXAMPLE_ITEM_VARIATION_ID_001",
                        "quantity_ordered": "5",
                    },
                    {
                        "item_variation_id": "EXAMPLE_ITEM_VARIATION_ID_002",
                        "quantity_ordered": "3",
                    },
                ],
            },
        )
        """
        _response = self._raw_client.create(
            idempotency_key=idempotency_key, transfer_order=transfer_order, request_options=request_options
        )
        return _response.data

    def search(
        self,
        *,
        query: typing.Optional[TransferOrderQueryParams] = OMIT,
        cursor: typing.Optional[str] = OMIT,
        limit: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SyncPager[TransferOrder, SearchTransferOrdersResponse]:
        """
        Searches for transfer orders using filters. Returns a paginated list of matching
        [TransferOrder](entity:TransferOrder)s sorted by creation date.

        Common search scenarios:
        - Find orders for a source [Location](entity:Location)
        - Find orders for a destination [Location](entity:Location)
        - Find orders in a particular [TransferOrderStatus](entity:TransferOrderStatus)

        Parameters
        ----------
        query : typing.Optional[TransferOrderQueryParams]
            The search query

        cursor : typing.Optional[str]
            Pagination cursor from a previous search response

        limit : typing.Optional[int]
            Maximum number of results to return (1-100)

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SyncPager[TransferOrder, SearchTransferOrdersResponse]
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        response = client.transfer_orders.search(
            query={
                "filter": {
                    "source_location_ids": ["EXAMPLE_SOURCE_LOCATION_ID_123"],
                    "destination_location_ids": ["EXAMPLE_DEST_LOCATION_ID_456"],
                    "statuses": ["STARTED", "PARTIALLY_RECEIVED"],
                },
                "sort": {"field": "UPDATED_AT", "order": "DESC"},
            },
            cursor="eyJsYXN0X3VwZGF0ZWRfYXQiOjE3NTMxMTg2NjQ4NzN9",
            limit=10,
        )
        for item in response:
            yield item
        # alternatively, you can paginate page-by-page
        for page in response.iter_pages():
            yield page
        """
        return self._raw_client.search(query=query, cursor=cursor, limit=limit, request_options=request_options)

    def get(
        self, transfer_order_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> RetrieveTransferOrderResponse:
        """
        Retrieves a specific [TransferOrder](entity:TransferOrder) by ID. Returns the complete
        order details including:

        - Basic information (status, dates, notes)
        - Line items with ordered and received quantities
        - Source and destination [Location](entity:Location)s
        - Tracking information (if available)

        Parameters
        ----------
        transfer_order_id : str
            The ID of the transfer order to retrieve

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        RetrieveTransferOrderResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.transfer_orders.get(
            transfer_order_id="transfer_order_id",
        )
        """
        _response = self._raw_client.get(transfer_order_id, request_options=request_options)
        return _response.data

    def update(
        self,
        transfer_order_id: str,
        *,
        idempotency_key: str,
        transfer_order: UpdateTransferOrderDataParams,
        version: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UpdateTransferOrderResponse:
        """
        Updates an existing transfer order. This endpoint supports sparse updates,
        allowing you to modify specific fields without affecting others.

        Creates a [transfer_order.updated](webhook:transfer_order.updated) webhook event.

        Parameters
        ----------
        transfer_order_id : str
            The ID of the transfer order to update

        idempotency_key : str
            A unique string that identifies this UpdateTransferOrder request. Keys must contain only alphanumeric characters, dashes and underscores

        transfer_order : UpdateTransferOrderDataParams
            The transfer order updates to apply

        version : typing.Optional[int]
            Version for optimistic concurrency

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UpdateTransferOrderResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.transfer_orders.update(
            transfer_order_id="transfer_order_id",
            idempotency_key="f47ac10b-58cc-4372-a567-0e02b2c3d479",
            transfer_order={
                "source_location_id": "EXAMPLE_SOURCE_LOCATION_ID_789",
                "destination_location_id": "EXAMPLE_DEST_LOCATION_ID_101",
                "expected_at": "2025-11-10T08:00:00Z",
                "notes": "Updated: Priority transfer due to low stock at destination",
                "tracking_number": "TRACK987654321",
                "line_items": [
                    {"uid": "1", "quantity_ordered": "7"},
                    {
                        "item_variation_id": "EXAMPLE_NEW_ITEM_VARIATION_ID_003",
                        "quantity_ordered": "2",
                    },
                    {"uid": "2", "remove": True},
                ],
            },
            version=1753109537351,
        )
        """
        _response = self._raw_client.update(
            transfer_order_id,
            idempotency_key=idempotency_key,
            transfer_order=transfer_order,
            version=version,
            request_options=request_options,
        )
        return _response.data

    def delete(
        self,
        transfer_order_id: str,
        *,
        version: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> DeleteTransferOrderResponse:
        """
        Deletes a transfer order in [DRAFT](entity:TransferOrderStatus) status.
        Only draft orders can be deleted. Once an order is started via
        [StartTransferOrder](api-endpoint:TransferOrders-StartTransferOrder), it can no longer be deleted.

        Creates a [transfer_order.deleted](webhook:transfer_order.deleted) webhook event.

        Parameters
        ----------
        transfer_order_id : str
            The ID of the transfer order to delete

        version : typing.Optional[int]
            Version for optimistic concurrency

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DeleteTransferOrderResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.transfer_orders.delete(
            transfer_order_id="transfer_order_id",
            version=1000000,
        )
        """
        _response = self._raw_client.delete(transfer_order_id, version=version, request_options=request_options)
        return _response.data

    def cancel(
        self,
        transfer_order_id: str,
        *,
        idempotency_key: str,
        version: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> CancelTransferOrderResponse:
        """
        Cancels a transfer order in [STARTED](entity:TransferOrderStatus) or
        [PARTIALLY_RECEIVED](entity:TransferOrderStatus) status. Any unreceived quantities will no
        longer be receivable and will be immediately returned to the source [Location](entity:Location)'s inventory.

        Common reasons for cancellation:
        - Items no longer needed at destination
        - Source location needs the inventory
        - Order created in error

        Creates a [transfer_order.updated](webhook:transfer_order.updated) webhook event.

        Parameters
        ----------
        transfer_order_id : str
            The ID of the transfer order to cancel. Must be in STARTED or PARTIALLY_RECEIVED status.

        idempotency_key : str
            A unique string that identifies this UpdateTransferOrder request. Keys can be
            any valid string but must be unique for every UpdateTransferOrder request.

        version : typing.Optional[int]
            Version for optimistic concurrency

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CancelTransferOrderResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.transfer_orders.cancel(
            transfer_order_id="transfer_order_id",
            idempotency_key="65cc0586-3e82-4d08-b524-3885cffd52",
            version=1753117449752,
        )
        """
        _response = self._raw_client.cancel(
            transfer_order_id, idempotency_key=idempotency_key, version=version, request_options=request_options
        )
        return _response.data

    def receive(
        self,
        transfer_order_id: str,
        *,
        idempotency_key: str,
        receipt: TransferOrderGoodsReceiptParams,
        version: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> ReceiveTransferOrderResponse:
        """
        Records receipt of [CatalogItemVariation](entity:CatalogItemVariation)s for a transfer order.
        This endpoint supports partial receiving - you can receive items in multiple batches.

        For each line item, you can specify:
        - Quantity received in good condition (added to destination inventory with [InventoryState](entity:InventoryState) of IN_STOCK)
        - Quantity damaged during transit/handling (added to destination inventory with [InventoryState](entity:InventoryState) of WASTE)
        - Quantity canceled (returned to source location's inventory)

        The order must be in [STARTED](entity:TransferOrderStatus) or [PARTIALLY_RECEIVED](entity:TransferOrderStatus) status.
        Received quantities are added to the destination [Location](entity:Location)'s inventory according to their condition.
        Canceled quantities are immediately returned to the source [Location](entity:Location)'s inventory.

        When all items are either received, damaged, or canceled, the order moves to
        [COMPLETED](entity:TransferOrderStatus) status.

        Creates a [transfer_order.updated](webhook:transfer_order.updated) webhook event.

        Parameters
        ----------
        transfer_order_id : str
            The ID of the transfer order to receive items for

        idempotency_key : str
            A unique key to make this request idempotent

        receipt : TransferOrderGoodsReceiptParams
            The receipt details

        version : typing.Optional[int]
            Version for optimistic concurrency

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        ReceiveTransferOrderResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.transfer_orders.receive(
            transfer_order_id="transfer_order_id",
            idempotency_key="EXAMPLE_IDEMPOTENCY_KEY_101",
            receipt={
                "line_items": [
                    {
                        "transfer_order_line_uid": "1",
                        "quantity_received": "3",
                        "quantity_damaged": "1",
                        "quantity_canceled": "1",
                    },
                    {
                        "transfer_order_line_uid": "2",
                        "quantity_received": "2",
                        "quantity_canceled": "1",
                    },
                ]
            },
            version=1753118664873,
        )
        """
        _response = self._raw_client.receive(
            transfer_order_id,
            idempotency_key=idempotency_key,
            receipt=receipt,
            version=version,
            request_options=request_options,
        )
        return _response.data

    def start(
        self,
        transfer_order_id: str,
        *,
        idempotency_key: str,
        version: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> StartTransferOrderResponse:
        """
        Changes a [DRAFT](entity:TransferOrderStatus) transfer order to [STARTED](entity:TransferOrderStatus) status.
        This decrements inventory at the source [Location](entity:Location) and marks it as in-transit.

        The order must be in [DRAFT](entity:TransferOrderStatus) status and have all required fields populated.
        Once started, the order can no longer be deleted, but it can be canceled via
        [CancelTransferOrder](api-endpoint:TransferOrders-CancelTransferOrder).

        Creates a [transfer_order.updated](webhook:transfer_order.updated) webhook event.

        Parameters
        ----------
        transfer_order_id : str
            The ID of the transfer order to start. Must be in DRAFT status.

        idempotency_key : str
            A unique string that identifies this UpdateTransferOrder request. Keys can be
            any valid string but must be unique for every UpdateTransferOrder request.

        version : typing.Optional[int]
            Version for optimistic concurrency

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        StartTransferOrderResponse
            Success

        Examples
        --------
        from square import Square

        client = Square(
            token="YOUR_TOKEN",
        )
        client.transfer_orders.start(
            transfer_order_id="transfer_order_id",
            idempotency_key="EXAMPLE_IDEMPOTENCY_KEY_789",
            version=1753109537351,
        )
        """
        _response = self._raw_client.start(
            transfer_order_id, idempotency_key=idempotency_key, version=version, request_options=request_options
        )
        return _response.data


class AsyncTransferOrdersClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawTransferOrdersClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> AsyncRawTransferOrdersClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        AsyncRawTransferOrdersClient
        """
        return self._raw_client

    async def create(
        self,
        *,
        idempotency_key: str,
        transfer_order: CreateTransferOrderDataParams,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> CreateTransferOrderResponse:
        """
        Creates a new transfer order in [DRAFT](entity:TransferOrderStatus) status. A transfer order represents the intent
        to move [CatalogItemVariation](entity:CatalogItemVariation)s from one [Location](entity:Location) to another.
        The source and destination locations must be different and must belong to your Square account.

        In [DRAFT](entity:TransferOrderStatus) status, you can:
        - Add or remove items
        - Modify quantities
        - Update shipping information
        - Delete the entire order via [DeleteTransferOrder](api-endpoint:TransferOrders-DeleteTransferOrder)

        The request requires source_location_id and destination_location_id.
        Inventory levels are not affected until the order is started via
        [StartTransferOrder](api-endpoint:TransferOrders-StartTransferOrder).

        Common integration points:
        - Sync with warehouse management systems
        - Automate regular stock transfers
        - Initialize transfers from inventory optimization systems

        Creates a [transfer_order.created](webhook:transfer_order.created) webhook event.

        Parameters
        ----------
        idempotency_key : str
            A unique string that identifies this CreateTransferOrder request. Keys can be
            any valid string but must be unique for every CreateTransferOrder request.

        transfer_order : CreateTransferOrderDataParams
            The transfer order to create

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CreateTransferOrderResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.transfer_orders.create(
                idempotency_key="65cc0586-3e82-384s-b524-3885cffd52",
                transfer_order={
                    "source_location_id": "EXAMPLE_SOURCE_LOCATION_ID_123",
                    "destination_location_id": "EXAMPLE_DEST_LOCATION_ID_456",
                    "expected_at": "2025-11-09T05:00:00Z",
                    "notes": "Example transfer order for inventory redistribution between locations",
                    "tracking_number": "TRACK123456789",
                    "created_by_team_member_id": "EXAMPLE_TEAM_MEMBER_ID_789",
                    "line_items": [
                        {
                            "item_variation_id": "EXAMPLE_ITEM_VARIATION_ID_001",
                            "quantity_ordered": "5",
                        },
                        {
                            "item_variation_id": "EXAMPLE_ITEM_VARIATION_ID_002",
                            "quantity_ordered": "3",
                        },
                    ],
                },
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.create(
            idempotency_key=idempotency_key, transfer_order=transfer_order, request_options=request_options
        )
        return _response.data

    async def search(
        self,
        *,
        query: typing.Optional[TransferOrderQueryParams] = OMIT,
        cursor: typing.Optional[str] = OMIT,
        limit: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> AsyncPager[TransferOrder, SearchTransferOrdersResponse]:
        """
        Searches for transfer orders using filters. Returns a paginated list of matching
        [TransferOrder](entity:TransferOrder)s sorted by creation date.

        Common search scenarios:
        - Find orders for a source [Location](entity:Location)
        - Find orders for a destination [Location](entity:Location)
        - Find orders in a particular [TransferOrderStatus](entity:TransferOrderStatus)

        Parameters
        ----------
        query : typing.Optional[TransferOrderQueryParams]
            The search query

        cursor : typing.Optional[str]
            Pagination cursor from a previous search response

        limit : typing.Optional[int]
            Maximum number of results to return (1-100)

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        AsyncPager[TransferOrder, SearchTransferOrdersResponse]
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            response = await client.transfer_orders.search(
                query={
                    "filter": {
                        "source_location_ids": ["EXAMPLE_SOURCE_LOCATION_ID_123"],
                        "destination_location_ids": ["EXAMPLE_DEST_LOCATION_ID_456"],
                        "statuses": ["STARTED", "PARTIALLY_RECEIVED"],
                    },
                    "sort": {"field": "UPDATED_AT", "order": "DESC"},
                },
                cursor="eyJsYXN0X3VwZGF0ZWRfYXQiOjE3NTMxMTg2NjQ4NzN9",
                limit=10,
            )
            async for item in response:
                yield item

            # alternatively, you can paginate page-by-page
            async for page in response.iter_pages():
                yield page


        asyncio.run(main())
        """
        return await self._raw_client.search(query=query, cursor=cursor, limit=limit, request_options=request_options)

    async def get(
        self, transfer_order_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> RetrieveTransferOrderResponse:
        """
        Retrieves a specific [TransferOrder](entity:TransferOrder) by ID. Returns the complete
        order details including:

        - Basic information (status, dates, notes)
        - Line items with ordered and received quantities
        - Source and destination [Location](entity:Location)s
        - Tracking information (if available)

        Parameters
        ----------
        transfer_order_id : str
            The ID of the transfer order to retrieve

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        RetrieveTransferOrderResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.transfer_orders.get(
                transfer_order_id="transfer_order_id",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get(transfer_order_id, request_options=request_options)
        return _response.data

    async def update(
        self,
        transfer_order_id: str,
        *,
        idempotency_key: str,
        transfer_order: UpdateTransferOrderDataParams,
        version: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UpdateTransferOrderResponse:
        """
        Updates an existing transfer order. This endpoint supports sparse updates,
        allowing you to modify specific fields without affecting others.

        Creates a [transfer_order.updated](webhook:transfer_order.updated) webhook event.

        Parameters
        ----------
        transfer_order_id : str
            The ID of the transfer order to update

        idempotency_key : str
            A unique string that identifies this UpdateTransferOrder request. Keys must contain only alphanumeric characters, dashes and underscores

        transfer_order : UpdateTransferOrderDataParams
            The transfer order updates to apply

        version : typing.Optional[int]
            Version for optimistic concurrency

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UpdateTransferOrderResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.transfer_orders.update(
                transfer_order_id="transfer_order_id",
                idempotency_key="f47ac10b-58cc-4372-a567-0e02b2c3d479",
                transfer_order={
                    "source_location_id": "EXAMPLE_SOURCE_LOCATION_ID_789",
                    "destination_location_id": "EXAMPLE_DEST_LOCATION_ID_101",
                    "expected_at": "2025-11-10T08:00:00Z",
                    "notes": "Updated: Priority transfer due to low stock at destination",
                    "tracking_number": "TRACK987654321",
                    "line_items": [
                        {"uid": "1", "quantity_ordered": "7"},
                        {
                            "item_variation_id": "EXAMPLE_NEW_ITEM_VARIATION_ID_003",
                            "quantity_ordered": "2",
                        },
                        {"uid": "2", "remove": True},
                    ],
                },
                version=1753109537351,
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.update(
            transfer_order_id,
            idempotency_key=idempotency_key,
            transfer_order=transfer_order,
            version=version,
            request_options=request_options,
        )
        return _response.data

    async def delete(
        self,
        transfer_order_id: str,
        *,
        version: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> DeleteTransferOrderResponse:
        """
        Deletes a transfer order in [DRAFT](entity:TransferOrderStatus) status.
        Only draft orders can be deleted. Once an order is started via
        [StartTransferOrder](api-endpoint:TransferOrders-StartTransferOrder), it can no longer be deleted.

        Creates a [transfer_order.deleted](webhook:transfer_order.deleted) webhook event.

        Parameters
        ----------
        transfer_order_id : str
            The ID of the transfer order to delete

        version : typing.Optional[int]
            Version for optimistic concurrency

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        DeleteTransferOrderResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.transfer_orders.delete(
                transfer_order_id="transfer_order_id",
                version=1000000,
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.delete(transfer_order_id, version=version, request_options=request_options)
        return _response.data

    async def cancel(
        self,
        transfer_order_id: str,
        *,
        idempotency_key: str,
        version: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> CancelTransferOrderResponse:
        """
        Cancels a transfer order in [STARTED](entity:TransferOrderStatus) or
        [PARTIALLY_RECEIVED](entity:TransferOrderStatus) status. Any unreceived quantities will no
        longer be receivable and will be immediately returned to the source [Location](entity:Location)'s inventory.

        Common reasons for cancellation:
        - Items no longer needed at destination
        - Source location needs the inventory
        - Order created in error

        Creates a [transfer_order.updated](webhook:transfer_order.updated) webhook event.

        Parameters
        ----------
        transfer_order_id : str
            The ID of the transfer order to cancel. Must be in STARTED or PARTIALLY_RECEIVED status.

        idempotency_key : str
            A unique string that identifies this UpdateTransferOrder request. Keys can be
            any valid string but must be unique for every UpdateTransferOrder request.

        version : typing.Optional[int]
            Version for optimistic concurrency

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CancelTransferOrderResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.transfer_orders.cancel(
                transfer_order_id="transfer_order_id",
                idempotency_key="65cc0586-3e82-4d08-b524-3885cffd52",
                version=1753117449752,
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.cancel(
            transfer_order_id, idempotency_key=idempotency_key, version=version, request_options=request_options
        )
        return _response.data

    async def receive(
        self,
        transfer_order_id: str,
        *,
        idempotency_key: str,
        receipt: TransferOrderGoodsReceiptParams,
        version: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> ReceiveTransferOrderResponse:
        """
        Records receipt of [CatalogItemVariation](entity:CatalogItemVariation)s for a transfer order.
        This endpoint supports partial receiving - you can receive items in multiple batches.

        For each line item, you can specify:
        - Quantity received in good condition (added to destination inventory with [InventoryState](entity:InventoryState) of IN_STOCK)
        - Quantity damaged during transit/handling (added to destination inventory with [InventoryState](entity:InventoryState) of WASTE)
        - Quantity canceled (returned to source location's inventory)

        The order must be in [STARTED](entity:TransferOrderStatus) or [PARTIALLY_RECEIVED](entity:TransferOrderStatus) status.
        Received quantities are added to the destination [Location](entity:Location)'s inventory according to their condition.
        Canceled quantities are immediately returned to the source [Location](entity:Location)'s inventory.

        When all items are either received, damaged, or canceled, the order moves to
        [COMPLETED](entity:TransferOrderStatus) status.

        Creates a [transfer_order.updated](webhook:transfer_order.updated) webhook event.

        Parameters
        ----------
        transfer_order_id : str
            The ID of the transfer order to receive items for

        idempotency_key : str
            A unique key to make this request idempotent

        receipt : TransferOrderGoodsReceiptParams
            The receipt details

        version : typing.Optional[int]
            Version for optimistic concurrency

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        ReceiveTransferOrderResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.transfer_orders.receive(
                transfer_order_id="transfer_order_id",
                idempotency_key="EXAMPLE_IDEMPOTENCY_KEY_101",
                receipt={
                    "line_items": [
                        {
                            "transfer_order_line_uid": "1",
                            "quantity_received": "3",
                            "quantity_damaged": "1",
                            "quantity_canceled": "1",
                        },
                        {
                            "transfer_order_line_uid": "2",
                            "quantity_received": "2",
                            "quantity_canceled": "1",
                        },
                    ]
                },
                version=1753118664873,
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.receive(
            transfer_order_id,
            idempotency_key=idempotency_key,
            receipt=receipt,
            version=version,
            request_options=request_options,
        )
        return _response.data

    async def start(
        self,
        transfer_order_id: str,
        *,
        idempotency_key: str,
        version: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> StartTransferOrderResponse:
        """
        Changes a [DRAFT](entity:TransferOrderStatus) transfer order to [STARTED](entity:TransferOrderStatus) status.
        This decrements inventory at the source [Location](entity:Location) and marks it as in-transit.

        The order must be in [DRAFT](entity:TransferOrderStatus) status and have all required fields populated.
        Once started, the order can no longer be deleted, but it can be canceled via
        [CancelTransferOrder](api-endpoint:TransferOrders-CancelTransferOrder).

        Creates a [transfer_order.updated](webhook:transfer_order.updated) webhook event.

        Parameters
        ----------
        transfer_order_id : str
            The ID of the transfer order to start. Must be in DRAFT status.

        idempotency_key : str
            A unique string that identifies this UpdateTransferOrder request. Keys can be
            any valid string but must be unique for every UpdateTransferOrder request.

        version : typing.Optional[int]
            Version for optimistic concurrency

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        StartTransferOrderResponse
            Success

        Examples
        --------
        import asyncio

        from square import AsyncSquare

        client = AsyncSquare(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.transfer_orders.start(
                transfer_order_id="transfer_order_id",
                idempotency_key="EXAMPLE_IDEMPOTENCY_KEY_789",
                version=1753109537351,
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.start(
            transfer_order_id, idempotency_key=idempotency_key, version=version, request_options=request_options
        )
        return _response.data
