---
title: "CreateTransferOrder"
method: POST
path: "/v2/transfer-orders"
tags: ["TransferOrder"]
---

# CreateTransferOrder

`POST /v2/transfer-orders`

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.

## Request body

- CreateTransferOrderRequest — Request to create a new transfer order.
  - `idempotency_key` string, required — A unique string that identifies this CreateTransferOrder request. Keys can be any valid string but must be unique for every CreateTransferOrder request.
  - `transfer_order` CreateTransferOrderData, required — Data for creating a new transfer order to move [CatalogItemVariation](entity:CatalogItemVariation)s between [Location](entity:Location)s. Used with the [CreateTransferOrder](api-endpoint:TransferOrders-CreateTransferOrder) endpoint.
    - `source_location_id` string, required — The source [Location](entity:Location) that will send the items. Must be an active location in your Square account with sufficient inventory of the requested items.
    - `destination_location_id` string, required — The destination [Location](entity:Location) that will receive the items. Must be an active location in your Square account
    - `expected_at` string, nullable — Expected transfer date in RFC 3339 format (e.g. "2023-10-01T12:00:00Z").
    - `notes` string, nullable — Optional notes about the transfer
    - `tracking_number` string, nullable — Optional shipment tracking number
    - `created_by_team_member_id` string, nullable — ID of the [TeamMember](entity:TeamMember) creating this transfer order. Used for tracking and auditing purposes.
    - `line_items` CreateTransferOrderLineData[], nullable — List of [CatalogItemVariation](entity:CatalogItemVariation)s to transfer, including quantities
      - `item_variation_id` string, required — ID of the [CatalogItemVariation](entity:CatalogItemVariation) to transfer. Must reference a valid item variation in the [Catalog](api:Catalog). The item variation must be: - Active and available for sale - Enabled for inventory tracking - Available at the source location
      - `quantity_ordered` string, required — Total quantity ordered

## Response `200`

Success

- CreateTransferOrderResponse — Response for creating a transfer order.
  - `transfer_order` TransferOrder — 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` string — 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` string, nullable — 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` string, nullable — 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` 'DRAFT' | 'STARTED' | 'PARTIALLY_RECEIVED' | 'COMPLETED' | 'CANCELED' — Status values for transfer orders. Represents the current state of a [TransferOrder](entity:TransferOrder) in its lifecycle from creation to completion. Each status determines what actions are available and how inventory is affected.
    - `created_at` string — Timestamp when the transfer order was created, in RFC 3339 format. Used for: - Auditing transfer history - Tracking order age - Reporting and analytics
    - `updated_at` string — 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` string, nullable — Expected transfer completion date, in RFC 3339 format. Used for: - Planning inventory availability - Scheduling receiving staff - Monitoring transfer timeliness
    - `completed_at` string — Timestamp when the transfer order was completed or canceled, in RFC 3339 format (e.g. "2023-10-01T12:00:00Z").
    - `notes` string, nullable — Optional notes about the transfer.
    - `tracking_number` string, nullable — Shipment tracking number for monitoring transfer progress.
    - `created_by_team_member_id` string — ID of the [TeamMember](entity:TeamMember) who created this transfer order. This field is not writeable by the Connect V2 API.
    - `line_items` TransferOrderLine[], nullable — List of [CatalogItemVariation](entity:CatalogItemVariation)s being transferred.
      - `uid` string — Unique system-generated identifier for the line item. Provide when updating/removing a line via [UpdateTransferOrder](api-endpoint:TransferOrders-UpdateTransferOrder).
      - `item_variation_id` string, required — The required identifier of the [CatalogItemVariation](entity:CatalogItemVariation) being transferred. Must reference a valid catalog item variation that exists in the [Catalog](api:Catalog).
      - `quantity_ordered` string, required — Total quantity ordered, formatted as a decimal string (e.g. "10 or 10.0000"). Required to be a positive number. To remove a line item, set `remove` to `true` in [UpdateTransferOrder](api-endpoint:TransferOrders-UpdateTransferOrder).
      - `quantity_pending` string — Calculated quantity of this line item's yet to be received stock. This is the difference between the total quantity ordered and the sum of quantities received, canceled, and damaged.
      - `quantity_received` string — Quantity received at destination. These items are added to the destination [Location](entity:Location)'s inventory with [InventoryState](entity:InventoryState) of IN_STOCK. This field cannot be updated directly in Create/Update operations, instead use [ReceiveTransferOrder](api-endpoint:TransferOrders-ReceiveTransferOrder).
      - `quantity_damaged` string — Quantity received in damaged condition. These items are added to the destination [Location](entity:Location)'s inventory with [InventoryState](entity:InventoryState) of WASTE. This field cannot be updated directly in Create/Update operations, instead use [ReceiveTransferOrder](api-endpoint:TransferOrders-ReceiveTransferOrder).
      - `quantity_canceled` string — Quantity that was canceled. These items will be immediately added to inventory in the source location. This field cannot be updated directly in Create/Update operations, instead use [ReceiveTransferOrder](api-endpoint:TransferOrders-ReceiveTransferOrder) or [CancelTransferOrder](api-endpoint:TransferOrders-CancelTransferOrder).
    - `version` integer — 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.
  - `errors` Error[] — Any errors that occurred during the request
    - `category` 'API_ERROR' | 'AUTHENTICATION_ERROR' | 'INVALID_REQUEST_ERROR' | 'RATE_LIMIT_ERROR' | 'PAYMENT_METHOD_ERROR' | 'REFUND_ERROR' | 'MERCHANT_SUBSCRIPTION_ERROR' | 'EXTERNAL_VENDOR_ERROR', required — Indicates which high-level category of error has occurred during a request to the Connect API.
    - `code` 'INTERNAL_SERVER_ERROR' | 'UNAUTHORIZED' | 'ACCESS_TOKEN_EXPIRED' | 'ACCESS_TOKEN_REVOKED' | 'CLIENT_DISABLED' | 'FORBIDDEN' | 'INSUFFICIENT_SCOPES' | 'APPLICATION_DISABLED' | 'V1_APPLICATION' | 'V1_ACCESS_TOKEN' | 'CARD_PROCESSING_NOT_ENABLED' | 'MERCHANT_SUBSCRIPTION_NOT_FOUND' | 'BAD_REQUEST' | 'MISSING_REQUIRED_PARAMETER' | 'INCORRECT_TYPE' | 'INVALID_TIME' | 'INVALID_TIME_RANGE' | 'INVALID_VALUE' | 'INVALID_CURSOR' | 'UNKNOWN_QUERY_PARAMETER' | 'CONFLICTING_PARAMETERS' | 'EXPECTED_JSON_BODY' | 'INVALID_SORT_ORDER' | 'VALUE_REGEX_MISMATCH' | 'VALUE_TOO_SHORT' | 'VALUE_TOO_LONG' | 'VALUE_TOO_LOW' | 'VALUE_TOO_HIGH' | 'VALUE_EMPTY' | 'ARRAY_LENGTH_TOO_LONG' | 'ARRAY_LENGTH_TOO_SHORT' | 'ARRAY_EMPTY' | 'EXPECTED_BOOLEAN' | 'EXPECTED_INTEGER' | 'EXPECTED_FLOAT' | 'EXPECTED_STRING' | 'EXPECTED_OBJECT' | 'EXPECTED_ARRAY' | 'EXPECTED_MAP' | 'EXPECTED_BASE64_ENCODED_BYTE_ARRAY' | 'INVALID_ARRAY_VALUE' | 'INVALID_ENUM_VALUE' | 'INVALID_CONTENT_TYPE' | 'INVALID_FORM_VALUE' | 'CUSTOMER_NOT_FOUND' | 'ONE_INSTRUMENT_EXPECTED' | 'NO_FIELDS_SET' | 'TOO_MANY_MAP_ENTRIES' | 'MAP_KEY_LENGTH_TOO_SHORT' | 'MAP_KEY_LENGTH_TOO_LONG' | 'CUSTOMER_MISSING_NAME' | 'CUSTOMER_MISSING_EMAIL' | 'INVALID_PAUSE_LENGTH' | 'INVALID_DATE' | 'UNSUPPORTED_COUNTRY' | 'UNSUPPORTED_CURRENCY' | 'APPLE_TTP_PIN_TOKEN' | 'CARD_EXPIRED' | 'INVALID_EXPIRATION' | 'INVALID_EXPIRATION_YEAR' | 'INVALID_EXPIRATION_DATE' | 'UNSUPPORTED_CARD_BRAND' | 'UNSUPPORTED_ENTRY_METHOD' | 'INVALID_ENCRYPTED_CARD' | 'INVALID_CARD' | 'PAYMENT_AMOUNT_MISMATCH' | 'GENERIC_DECLINE' | 'CVV_FAILURE' | 'ADDRESS_VERIFICATION_FAILURE' | 'INVALID_ACCOUNT' | 'CURRENCY_MISMATCH' | 'INSUFFICIENT_FUNDS' | 'INSUFFICIENT_PERMISSIONS' | 'CARDHOLDER_INSUFFICIENT_PERMISSIONS' | 'INVALID_LOCATION' | 'TRANSACTION_LIMIT' | 'VOICE_FAILURE' | 'PAN_FAILURE' | 'EXPIRATION_FAILURE' | 'CARD_NOT_SUPPORTED' | 'READER_DECLINED' | 'INVALID_PIN' | 'MISSING_PIN' | 'MISSING_ACCOUNT_TYPE' | 'INVALID_POSTAL_CODE' | 'INVALID_FEES' | 'MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED' | 'PAYMENT_LIMIT_EXCEEDED' | 'GIFT_CARD_AVAILABLE_AMOUNT' | 'ACCOUNT_UNUSABLE' | 'BUYER_REFUSED_PAYMENT' | 'DELAYED_TRANSACTION_EXPIRED' | 'DELAYED_TRANSACTION_CANCELED' | 'DELAYED_TRANSACTION_CAPTURED' | 'DELAYED_TRANSACTION_FAILED' | 'CARD_TOKEN_EXPIRED' | 'CARD_TOKEN_USED' | 'AMOUNT_TOO_HIGH' | 'UNSUPPORTED_INSTRUMENT_TYPE' | 'REFUND_AMOUNT_INVALID' | 'REFUND_ALREADY_PENDING' | 'PAYMENT_NOT_REFUNDABLE' | 'PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE' | 'REFUND_ERROR_PAYMENT_NEEDS_COMPLETION' | 'REFUND_DECLINED' | 'INSUFFICIENT_PERMISSIONS_FOR_REFUND' | 'INVALID_CARD_DATA' | 'SOURCE_USED' | 'SOURCE_EXPIRED' | 'UNSUPPORTED_LOYALTY_REWARD_TIER' | 'LOCATION_MISMATCH' | 'ORDER_UNPAID_NOT_RETURNABLE' | 'PARTIAL_PAYMENT_DELAY_CAPTURE_NOT_SUPPORTED' | 'IDEMPOTENCY_KEY_REUSED' | 'UNEXPECTED_VALUE' | 'SANDBOX_NOT_SUPPORTED' | 'INVALID_EMAIL_ADDRESS' | 'INVALID_PHONE_NUMBER' | 'CHECKOUT_EXPIRED' | 'BAD_CERTIFICATE' | 'INVALID_SQUARE_VERSION_FORMAT' | 'API_VERSION_INCOMPATIBLE' | 'CARD_PRESENCE_REQUIRED' | 'UNSUPPORTED_SOURCE_TYPE' | 'CARD_MISMATCH' | 'PLAID_ERROR' | 'PLAID_ERROR_ITEM_LOGIN_REQUIRED' | 'PLAID_ERROR_RATE_LIMIT' | 'PAYMENT_SOURCE_NOT_ENABLED_FOR_TARGET' | 'CARD_DECLINED' | 'VERIFY_CVV_FAILURE' | 'VERIFY_AVS_FAILURE' | 'CARD_DECLINED_CALL_ISSUER' | 'CARD_DECLINED_VERIFICATION_REQUIRED' | 'BAD_EXPIRATION' | 'CHIP_INSERTION_REQUIRED' | 'ALLOWABLE_PIN_TRIES_EXCEEDED' | 'RESERVATION_DECLINED' | 'UNKNOWN_BODY_PARAMETER' | 'NOT_FOUND' | 'APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'NOT_ACCEPTABLE' | 'REQUEST_TIMEOUT' | 'CONFLICT' | 'GONE' | 'REQUEST_ENTITY_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'UNPROCESSABLE_ENTITY' | 'RATE_LIMITED' | 'NOT_IMPLEMENTED' | 'BAD_GATEWAY' | 'SERVICE_UNAVAILABLE' | 'TEMPORARY_ERROR' | 'GATEWAY_TIMEOUT', required — Indicates the specific error that occurred during a request to a Square API.
    - `detail` string — A human-readable description of the error for debugging purposes.
    - `field` string — The name of the field provided in the original request (if any) that the error pertains to.

---

[API](https://skmtc.net/square/apis/connect-api.md) · [All operations](https://skmtc.net/square/apis/connect-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/connect-api/revisions/6a5164284e41/schema)