ZenotiHelp

Bulk transfer order API β€” Get, Save, and Delete

ZTZenoti Docs Team Updated October 27, 2026 9 min readGuide

Audience: Center admin, inventory manager, or integration developer coordinating Zenoti inventory data through the API.


On this page


The bulk transfer order (TO) API lets you retrieve, create, update, and delete multiple transfer orders in a single operation. Each operation is scoped to the organization and processes individual orders independently, so a failure on one transfer order does not roll back the others in the batch.

Note: For conceptual background on transfer orders β€” including lifecycle statuses, editable and non-editable fields, and the difference between source and destination centers β€” see Transfer Orders overview.

Before you begin

  • Your organization must have an active inventory configuration. Transfer orders require a source center and a destination center to be set up within the same organization.

  • You must have the following permissions under the Inventory security section:

    Permission: Delete Products β€” Required to delete transfer orders via the bulk delete operation. Admin path: Configuration > Security > Security Roles > [your role] > Products > Delete Products

    Permission: Inventory Orders Report β€” Required to retrieve and view transfer order data via the bulk GET operation. Admin path: Configuration > Security > Security Roles > [your role] > Reports(V2) > Inventory > Inventory Orders Report

    Permission: Returns Report β€” Required to retrieve return transfer order data via the bulk GET operation. Admin path: Configuration > Security > Security Roles > [your role] > Reports(V2) > Inventory > Returns Report

  • Confirm the transfer order (TO) numbers or IDs you intend to operate on. The bulk GET and DELETE operations accept a set of keys β€” either the internal TransferOrderId or the organization-assigned OrgTONumber.

  • Ensure the transfer orders you plan to delete are not in In transit status and are not fully closed (delivered with a closed flag). Both conditions result in rejection errors. See Understand rejection errors below.

Steps

Retrieve transfer orders in bulk (GET)

The bulk GET operation accepts a set of keys β€” either TransferOrderId or OrgTONumber values β€” and returns two result sets:

  • Result set 1 β€” Order headers: One row per requested key, containing header-level details for each resolved transfer order. Header details include the source center, destination center, current status, relevant dates, and charges.
  • Result set 2 β€” Line items: One row per live product line item across all resolved transfer orders.

Note: Keys that do not resolve to a transfer order within the organization are silently omitted from the response. Validate your input key set before calling the operation if completeness is critical.

To retrieve transfer orders in bulk:

  1. Prepare your set of transfer order keys. You may use either TransferOrderId values (internal system IDs) or OrgTONumber values (organization-assigned numbers) β€” not a mix of both in the same request.

  2. Submit the bulk GET request scoped to your organization, passing the key set as the input parameter.

  3. Review the two result sets returned:

    • In result set 1, confirm the header rows for each resolved transfer order. Each row includes the source center, destination center, status, dates (created, raised, in transit, delivered), and order-level charges.
    • In result set 2, review the line item rows. Each row corresponds to a live product line on a resolved transfer order.
  4. Use the returned data as needed β€” for example, to populate an external system, verify order details before an update, or audit order history.

Tip: The status values returned in result set 1 correspond to the TO lifecycle: Created, Raised, Updated, In transit, Partially delivered, Delivered, and Reconciled. For definitions, see the Transfer Orders overview.


Create or update transfer orders in bulk (SAVE)

The bulk SAVE operation supports both creating new transfer orders and updating existing ones. You specify the action for each order in the batch:

  • Create (Action = 1) β€” Creates a new transfer order.
  • Update (Action = 2) β€” Updates an existing transfer order.

Each transfer order in the batch is processed in its own transaction. A failure on one order does not roll back the others.

The target-status parameter controls the lifecycle stage you want the transfer order to reach. The supported target statuses span the full TO lifecycle:

Target status Description
Draft Saved but not yet formally created
Created Initial recorded state
Raised Submitted and dispatched to the destination center
In transit Products in transit between centers
Partially delivered Some products received at the destination center
Fully delivered All products received at the destination center
Closed Order finalized; no further transactions allowed

Important: Before submitting a SAVE operation that moves a transfer order to In transit or beyond, verify that the source center has sufficient stock. Insufficient stock at the source center may cause line-item failures. Stock quantities are tracked per center and are not shared across centers.

To create or update transfer orders in bulk:

  1. Prepare your batch payload. For each transfer order in the batch, specify:

    • Action β€” 1 for create, 2 for update.
    • Target status β€” The lifecycle stage you want the order to reach after the operation.
    • Order details β€” Source center, destination center, products, quantities, and any order-level charges relevant to the target status.
  2. Submit the bulk SAVE request to the organization.

  3. Review the response for each order in the batch:

    • Orders processed successfully return confirmation with the assigned TransferOrderId or OrgTONumber.
    • Orders that fail return an error for that specific order. Other orders in the batch are not affected.
  4. For any failed orders, review the error details, correct the input, and resubmit those orders individually or as a separate batch.

Important: Certain fields on a transfer order become non-editable once the order has been raised. For the full list of non-editable fields at each lifecycle stage, see the Transfer Orders overview.

Worked example:

You need to create three transfer orders from your warehouse center to three retail centers, all in Created status, and immediately raise one of them to Raised status for same-day dispatch.

  • Order A: Action = 1, target-status = Created, source = Warehouse, destination = Center North, 20 units of Product X.
  • Order B: Action = 1, target-status = Created, source = Warehouse, destination = Center East, 15 units of Product Y.
  • Order C: Action = 1, target-status = Raised, source = Warehouse, destination = Center South, 10 units of Product Z.

Submit all three in one bulk SAVE request. Orders A and B are saved as Created; Order C is saved and immediately raised to Raised. If Order B fails due to insufficient stock of Product Y at the warehouse, Orders A and C still succeed.


Delete transfer orders in bulk (DELETE)

The bulk DELETE operation accepts a set of transfer order keys and deletes each valid transfer order individually. The operation first validates the full set of keys, then processes each deletion separately.

Rejection conditions:

Two conditions cause a transfer order to be rejected and excluded from deletion:

Condition Error code Meaning
Transfer order status is In transit GE002 Orders in transit cannot be deleted. Resolve the in-transit status first.
Transfer order is fully closed (delivered and closed) IC240 Closed orders cannot be deleted.

Important: Rejected orders do not prevent the remaining valid orders in the batch from being deleted. Each deletion is processed individually after the initial key-set validation.

To delete transfer orders in bulk:

  1. Prepare your set of transfer order keys β€” either TransferOrderId or OrgTONumber values.

  2. Before submitting the DELETE request, verify that none of the targeted transfer orders are currently in In transit status or are fully closed. Use the bulk GET operation to check order statuses if needed.

  3. Submit the bulk DELETE request scoped to your organization, passing the key set.

  4. Review the response:

    • Transfer orders that were successfully deleted are confirmed in the response.
    • Transfer orders rejected with GE002 are in In transit and were not deleted.
    • Transfer orders rejected with IC240 are fully closed and were not deleted.
  5. For orders rejected with GE002, wait for the transfer order to be delivered or take action to update its status through the normal delivery workflow before attempting deletion again. For orders rejected with IC240, no deletion is possible β€” closed transfer orders are a permanent record.

Tip: To avoid GE002 errors, use the bulk GET operation first to confirm the current status of all orders you intend to delete. Filter out any orders in In transit status before submitting the DELETE request.

Tips

  • Validate keys before submitting. Use the bulk GET operation to confirm that your TransferOrderId or OrgTONumber values resolve to valid transfer orders before running a SAVE or DELETE operation on them.
  • Process large batches in segments. Because each order in a batch is processed independently, a large batch with many failures can be difficult to reconcile. Consider segmenting large batches by status or center to make error diagnosis faster.
  • Use the target-status parameter deliberately on SAVE. Moving a transfer order directly to In transit or Fully delivered in a single SAVE call skips intermediate lifecycle steps. Confirm that the source center stock levels and destination center receiving configuration support the target status before submitting.
  • Track OrgTONumber in your external system. The organization-assigned OrgTONumber is more portable across integrations than the internal TransferOrderId. Use it as the primary reference key in your external system where possible.

Troubleshooting

Error GE002 β€” Transfer order cannot be deleted (In transit)

  • Symptom: A DELETE request returns GE002 for one or more transfer orders.
  • Cause: The transfer order's stored status is In transit. Orders actively in transit cannot be deleted.
  • Resolution: Use the delivery workflow to mark the transfer order as Partially delivered or Fully delivered at the destination center. Once the status changes out of In transit, the order can be deleted if it has not yet been fully closed. Alternatively, exclude the order from your DELETE batch and retry only after the status changes.

Error IC240 β€” Transfer order cannot be deleted (fully closed)

  • Symptom: A DELETE request returns IC240 for one or more transfer orders.
  • Cause: The transfer order is fully closed β€” it has been delivered and the closed flag is set. Closed orders are permanent records and cannot be deleted.
  • Resolution: Closed transfer orders cannot be deleted through any path. If the order was closed in error, contact your Zenoti administrator to review the situation. Deletion is not possible after an order reaches this state.

Bulk SAVE returns mixed results β€” some orders fail, others succeed

  • Symptom: The SAVE response shows some orders created or updated successfully and others with errors.
  • Cause: Each order in the batch is processed in its own transaction. Failures on individual orders do not affect others. Common causes of individual failures include invalid product codes, insufficient stock at the source center, or attempting to update a field that is non-editable at the current lifecycle stage.
  • Resolution: Review the error details for each failed order. Correct the specific issues β€” for example, verify product codes against your product master, confirm on-hand quantities at the source center, or check which fields are editable at the order's current status. Resubmit the corrected orders in a new SAVE batch.

Bulk GET returns fewer rows than expected

  • Symptom: The GET response includes fewer header rows than the number of keys submitted.
  • Cause: Keys that do not resolve to a transfer order within the organization are silently omitted from the response.
  • Resolution: Verify that each key in your input set corresponds to a valid transfer order scoped to your organization. Use the Inventory > Orders screen to confirm that the transfer orders exist and are visible under the correct organization.
Was this article helpful?
Your feedback helps us improve our documentation.