Manage Transfer Orders

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

Learn how to use the Transfer Orders API to manage inventory transfers between a seller's locations.

This guide walks you through a complete transfer order workflow using the Transfer Orders API. The example uses a fictional running shoe retailer with stores in Tacoma, WA and Olympia, WA, as they transfer inventory between locations.

The example shows how to:

• Create a draft transfer order.
• Add or remove shoe variations from the draft.
• Delete a draft if plans change.
• Start the transfer when shoes leave Tacoma for Olympia.
• Cancel an in-progress transfer if needed.
• Receive the shipment at the Olympia store to complete the transfer.

Each step includes real API requests and responses, demonstrating how the Transfer Orders API works with the Inventory API to track item movement, update stock states (from IN_STOCK to IN_TRANSIT to IN_STOCK), and maintain accurate inventory counts at both locations throughout the transfer lifecycle.

For more details about the transfer order lifecycle, see How transfer orders work.

The Olympia store manager at Fleet Foot Running Co. needs to restock the popular New Balance FuelCell racing flat in multiple sizes. After checking the Square Dashboard, they find that the Tacoma store has sufficient stock to transfer half their inventory without creating shortages. The Olympia store manager asks the Tacoma store manager to create a draft transfer order. Keeping it in draft status allows time to review other inventory needs and potentially add more items to optimize the shipment.

Before creating the transfer order, the Tacoma store manager runs a SearchCatalogItems query to get the variation IDs for the New Balance FuelCell shoe variations in all sizes.

The Tacoma store manager uses your application to call CreateTransferOrder to create a draft transfer order for pairs of FuelCell shoes in sizes 8, 8.5, 9, and 9.5.

The Olympia store manager gets a call from the local high school track coach asking for women's racing flats for their 5,000 meter runners. There isn't enough stock in the needed sizes so the manager adds the women's FuelCell shoes to the draft transfer order. Your application calls the UpdateTransferOrder endpoint.

The following example makes the request with the ID of the transfer order to update, its current version number, and the new line item to add:

If the Olympia store manager decides to cancel their request for the shoe transfer, your application uses the following DeleteTransferOrder endpoint call to delete the transfer order:

Now that the Olympia store manager is satisfied with the list of shoes to be transferred, they let the Tacoma store know that there are no additional shoes to be transferred. The Tacoma store manager starts the transfer order using the StartTransferOrder endpoint, prints a physical copy of the transfer using your application, and asks their shipping department to send the shoes to Olympia.

Now that the transfer order has started, it can no longer be deleted. Instead, the order can be canceled and any shoes that haven't been received by the Olympia store are returned to inventory in Tacoma.

Unlike a draft transfer order, which can be deleted, a transfer order that is started and potentially even partially received can be only be canceled or completed. When canceled, any non-received items are returned to the source location's inventory. Any already received items remain at the receiving location. Call the CancelTransferOrder endpoint to cancel the transfer order.

At the Olympia store, the manager opens your application to acknowledge the receipt of all pairs of shoes except for the women's shoes that Tacoma didn't send. The Olympia store manager decided to cancel the transfer of the two pairs of women's shoes.

The call to the ReceiveTransferOrder endpoint includes a list of TransferOrderGoodsReceiptLineItem objects, one for each item variation in the transfer order. You put the actual count of items received, damaged in transit, or canceled in these objects.

The managers of the Tacoma and Olympia stores might want to review the current stock levels of all FuelCell sizes after the transfer is complete. The Transfer Orders API only reports on the quantity of items being transferred and not the new stock levels at either location after the transfer. To learn about reporting on inventory stock levels after a transfer, see Inventory Management Reporting.

• Transfer Orders API
• Inventory Management Reporting
• Transfer Orders Webhooks