Sign in

v1

latestOpenAPI 3.0.0Apache 2.02026-07-143281,4552.1 MB
TransferOrder

CreateTransferOrder

Creates a new transfer order in DRAFT status. A transfer order represents the intent to move CatalogItemVariations from one Location to another. The source and destination locations must be different and must belong to your Square account.

In DRAFT status, you can:

  • Add or remove items
  • Modify quantities
  • Update shipping information
  • Delete the entire order via DeleteTransferOrder

The request requires source_location_id and destination_location_id. Inventory levels are not affected until the order is started via 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 event.

post/v2/transfer-orders

Request body

idempotency_keystring required

A unique string that identifies this CreateTransferOrder request. Keys can be any valid string but must be unique for every CreateTransferOrder request.

Example request

{
  "idempotency_key": "65cc0586-3e82-384s-b524-3885cffd52",
  "transfer_order": {
    "created_by_team_member_id": "EXAMPLE_TEAM_MEMBER_ID_789",
    "destination_location_id": "EXAMPLE_DEST_LOCATION_ID_456",
    "expected_at": "2025-11-09T05:00:00Z",
    "line_items": [
      {
        "item_variation_id": "EXAMPLE_ITEM_VARIATION_ID_001",
        "quantity_ordered": "5"
      },
      {
        "item_variation_id": "EXAMPLE_ITEM_VARIATION_ID_002",
        "quantity_ordered": "3"
      }
    ],
    "notes": "Example transfer order for inventory redistribution between locations",
    "source_location_id": "EXAMPLE_SOURCE_LOCATION_ID_123",
    "tracking_number": "TRACK123456789"
  }
}

Response

Success

Example response

{
  "transfer_order": {
    "created_at": "2025-01-15T10:30:00Z",
    "created_by_team_member_id": "EXAMPLE_TEAM_MEMBER_ID_789",
    "destination_location_id": "EXAMPLE_DEST_LOCATION_ID_456",
    "expected_at": "2025-11-09T05:00:00Z",
    "id": "EXAMPLE_TRANSFER_ORDER_ID_123",
    "line_items": [
      {
        "item_variation_id": "EXAMPLE_ITEM_VARIATION_ID_001",
        "quantity_canceled": "0",
        "quantity_damaged": "0",
        "quantity_ordered": "5",
        "quantity_pending": "5",
        "quantity_received": "0",
        "uid": "1"
      },
      {
        "item_variation_id": "EXAMPLE_ITEM_VARIATION_ID_002",
        "quantity_canceled": "0",
        "quantity_damaged": "0",
        "quantity_ordered": "3",
        "quantity_pending": "3",
        "quantity_received": "0",
        "uid": "2"
      }
    ],
    "notes": "Example transfer order for inventory redistribution between locations",
    "source_location_id": "EXAMPLE_SOURCE_LOCATION_ID_123",
    "status": "DRAFT",
    "tracking_number": "TRACK123456789",
    "updated_at": "2025-01-15T10:30:00Z",
    "version": 1753109537351
  }
}