Import and export orders

Use this page to bring orders into Carriyo in bulk and to export the current order list for reporting or reconciliation.

Importing orders via the API

Use POST /orders/bulk/import to create or update up to 20 orders in a single request. Each order in the batch is processed independently — failures on one row do not block the others.

Create-or-update behavior

The endpoint matches each incoming order by its partner_order_reference:

Scenario	Behavior
No existing order with that reference	A new order is created (same as POST /orders).
Existing order in open, partially_allocated, or allocated	The order is updated using partial-merge logic (same as PATCH /orders/{reference}).
Existing order in processing, fulfilled, closed, or cancelled	The row is rejected. Use the single-order update endpoint instead.
Duplicate partner_order_reference within the same batch	All rows sharing that reference are rejected. Deduplicate before sending.

What "partial merge" means for updates

When an existing order is updated through bulk import, the behavior matches the single-order PATCH endpoint:

• Only non-null fields in the request overwrite existing values.
• Fulfillment orders are matched by fulfillment_order_id or partner_fulfillment_order_reference. Fulfilled and cancelled line items are preserved automatically.
• Line item quantity reductions are tracked as removed quantities.
• Inventory deltas are computed when inventory management is enabled.
• An ORDER_UPDATE webhook fires (not ORDER_CREATE).

Reading the response

Each row in the response carries a result and optional reason:

result	reason	Meaning
accepted	null	New order created.
accepted	"Existing order updated"	Existing order was updated.
rejected	Error message	Validation failed, status not eligible, or duplicate within batch.

Limits

Up to 20 orders per request by default (configurable per tenant). For larger imports, chunk the requests client-side.

Importing orders via the Dashboard

• Dashboard path: Orders > Import.
• Step 1: Download the Carriyo import template.
• Step 2: Fill in the template (one row per line item, grouped by order reference).
• Step 3: Upload the file. Progress shows in the sidebar.

Exporting orders

• Dashboard path: Orders > Export.
• Filters applied to the list are applied to the export.
• File format: CSV.

Concepts behind this

• Orders
• Order lifecycle
• Bulk import API reference