Transfer Orders API

Applies to: Transfer Orders API | Inventory API | Catalog API | Locations API | Team API

Learn about ordering and receiving items from another seller location by using the Transfer Orders API.

The Transfer Orders API lets you build applications that manage and track inventory movements between a seller's Square locations. When implementing inventory management features, you can use this API to programmatically handle stock transfers while maintaining consistency with the seller's catalog and inventory data.

Building on the foundations of Square's Catalog API and Inventory API, the Transfer Orders API lets you add stock transfer capabilities to your inventory management applications. Your application can create transfer orders using the seller's existing catalog item variations, and Square automatically handles the corresponding inventory adjustments. This means you can implement transfer order functionality without building custom inventory tracking logic or maintaining separate item mappings.

Square sellers who subscribe to Square Plus can create and update stock transfer orders from the Square Stand or Square Dashboard. These transfer orders can be retrieved and updated with the Transfer Orders API. You can also create and update transfer orders from your application using the API.

To implement the Transfer Orders API in your application, you need:

• A Square account for testing.
• OAuth 2.0 implementation with the following permissions:
  • INVENTORY_READ
  • INVENTORY_WRITE
• Catalog items that are:
  • Active in the seller's catalog.
  • Enabled for inventory tracking.
  • Stocked at the source location.

A transfer order is an object that tracks the movement of inventory items between a seller's locations. When creating a transfer order in your application, you specify:

• The source location sending the items.
• The destination location receiving the items.
• An array of catalog item variations and their quantities.
• Optional metadata such as expected delivery dates and tracking information.

Square maintains the transfer order's status and automatically handles inventory adjustments when your application updates the transfer order through its lifecycle.

The Transfer Orders API provides endpoints that let you implement inventory transfer functionality in your applications, with automatic inventory adjustments handled by Square at each stage of the transfer lifecycle. You can:

• Create transfer orders using existing catalog item variations.
• Track the transfer status through a well-defined state machine.
• Record item receipts with support for damaged or missing items.
• Search and retrieve the transfer order history.
• Let Square handle all inventory adjustments automatically.

Your application interacts with transfer orders through a defined state machine.

At several points in the transfer order lifecycle, Square creates Inventory API InventoryChange or InventoryCount records to document the movement of transferred items.

1. DRAFT - The initial state after creation.

   • You can modify or delete the order.
   • No inventory adjustments occur.
   • This is useful for staged order creation.

2. STARTED - The transfer is initiated.

   • Square decrements inventory from the source location.
   • An InventoryAdjustment is created for each item to document its in-transit status.
   • Deletion is no longer allowed.
   • Call when the physical transfer begins.

3. PARTIALLY_RECEIVED - A partial receipt is recorded.

   • Your application has recorded some received quantities.
   • Remaining quantities stay in transit.
   • Additional receipt calls are allowed.
   • Use for multi-part deliveries.

4. COMPLETED - The transfer is finished.

   • All quantities are received or canceled.
   • No pending quantities remain.
   • Only metadata updates are allowed.
   • The final state for successful transfers.

5. CANCELED - The transfer is canceled.

   • Square returns pending quantities to their source.
   • Only metadata updates are allowed.
   • Use when a transfer won't complete.

Square automatically handles these inventory state changes when your application updates a transfer order:

1. When you start a transfer:

   • Source location - IN_STOCK → IN_TRANSIT

2. When you record receipt:

   • Good condition - IN_TRANSIT → IN_STOCK (at its destination)
   • Damaged items - IN_TRANSIT → WASTE (at its destination)
   • Canceled items - IN_TRANSIT → IN_STOCK (returned to its source)

The Transfer Orders API supports various inventory management features you might need to implement:

• Automate stock redistribution between locations
• Implement min/max inventory-level maintenance
• Build demand-based transfer workflows

• Automate new location stocking
• Handle location closure inventory redistribution
• Support seasonal location transfers

• Manage temporary location transfers
• Implement return workflows
• Track event-specific inventory

• Build warehouse management features
• Implement distribution center workflows
• Support bulk transfer operations

When implementing the Transfer Orders API, you interact with these related APIs:

• Catalog API - Transfer order line items refer to the catalog item variations that are being transferred.
• Inventory API - Check stock levels, adjustments, and transfers.
• Locations API - Search for transfer orders by location ID.
• Team API - Associate team members with transfer operations.

To integrate the Transfer Orders API into your application:

1. Review the Manage Transfer Orders for implementation basics.
2. Study the Inventory Management Reporting for reporting on inventory transfer activity.
3. Follow the Transfer Order Webhooks guide to learn how to respond to inventory transfer events.

The Transfer Orders API is in Beta. While developing your integration:

• Monitor the release notes for updates.
• Test extensively in the Square Sandbox environment.
• Implement robust error handling.
• Follow Square's versioning guidelines.
• Consider future Beta phase changes.