Orders API

Creates a new order in Carriyo with the specified line items, customer details, and delivery method.

Order creation flow

When you create an order:

1. Carriyo validates the request and creates the order
2. Fulfillment orders are generated based on your specifications or automatic allocation
3. If inventory management is enabled, inventory is reserved for the allocated items
4. Webhooks are triggered to notify your systems

Delivery Method

Each fulfillment order can have one of three delivery methods:

• DELIVERY: standard delivery to the customer's address (delivery_address + delivery_schedule).
• COLLECTION: customer collects from a pickup point (customer_collection_address + customer_collection_schedule).
• DIGITAL: no physical delivery; fulfilled digitally.

The top-level delivery_method, delivery_type, delivery_address, delivery_schedule, customer_collection_address, and customer_collection_schedule are request-only convenience fields. They are propagated to each auto-allocated fulfillment order and persisted there, but are not stored on the Order itself. To set them per fulfillment order, provide them inside each entry of the fulfillment_orders array.

Fulfillment order allocation

You can control how fulfillment orders are created:

• Automatic: Omit fulfillment_orders and Carriyo allocates based on inventory and rules
• Manual: Specify fulfillment_orders to control which items go to which locations

Line items

Each line item represents a product in the order with:

• Product identification (id, sku, product_id, barcode)
• Quantity ordered
• Pricing information (unit_price, unit_cost, taxes, duties, discount allocations)
• Physical attributes (weight, dimension, dangerous_goods, battery)

Response

The API returns the complete order object including:

• Generated order_id for future reference
• Fulfillment orders with their allocations
• Initial order status

Retrieves the complete details of an order by its reference.

Reference Types

You can retrieve an order using:

• Carriyo Order ID: The unique identifier generated by Carriyo (default)
• partner_order_reference: Your system's order reference by setting key=partner_order_reference

Response

Returns the full order object including:

• Order details and status
• All fulfillment orders and their current states
• Line item details and fulfillment status
• Customer and address information

Apply partial updates to an order's details, line items, and fulfillment orders.

Important warning

Used incorrectly, this endpoint can destroy data. The fulfillment_orders field is a full replacement: any fulfillment order not included in the request is permanently removed.

Update behaviour

Simple fields (partial update)

The following fields are updated only if provided in the request:

• partner_order_reference, order_date, merchant, language, sales_channel
• taxes_included, duties_included
• delivery_address, billing_address, customer
• payment, discount_applications, shipping_lines

Line items (full replacement)

If line_items is provided, it completely replaces the existing line items. Include every line item you want to keep.

Fulfillment orders (full replacement with preservation rules)

If fulfillment_orders is provided:

• Any FO not included is removed. Always include every FO you want to keep.
• FOs are matched by fulfillment_order_id or partner_fulfillment_order_reference.
• An FO without a matching ID is created with a new fulfillment_order_id.

Fulfillment order line items: critical rules

When updating FO line items:

What to include

Only pass line items with pending statuses:

• open: items not yet allocated.
• allocated: items allocated but not fulfilled.

What is preserved automatically

Line items with terminal statuses are preserved without you re-sending them:

• fulfilled: items that have been fulfilled.
• cancelled: items that have been cancelled.
• closed: items that are closed.

Don't include fulfilled, cancelled, or closed line items in your request; they're preserved automatically and including them may cause unexpected behaviour.

Example scenarios

Scenario 1: adding a new line item to an FO

If you have an FO with 2 items (item-1: open, item-2: fulfilled) and want to add item-3:

{
  "fulfillment_orders": [{
    "fulfillment_order_id": "FO-123",
    "line_items": [
      { "id": "item-1", "quantity": 1 },
      { "id": "item-3", "quantity": 2 }
    ]
  }]
}

Result: the FO has item-1 (open), item-2 (fulfilled, preserved), item-3 (open).

Scenario 2: removing a pending line item from an FO

If you have an FO with 3 items and want to remove item-2 (which is open):

{
  "fulfillment_orders": [{
    "fulfillment_order_id": "FO-123",
    "line_items": [
      { "id": "item-1", "quantity": 1 },
      { "id": "item-3", "quantity": 1 }
    ]
  }]
}

Scenario 3: moving a line item between FOs

To move item-2 from FO-A to FO-B:

{
  "fulfillment_orders": [
    {
      "fulfillment_order_id": "FO-A",
      "line_items": [{ "id": "item-1", "quantity": 1 }]
    },
    {
      "fulfillment_order_id": "FO-B",
      "line_items": [
        { "id": "item-2", "quantity": 1 },
        { "id": "item-3", "quantity": 1 }
      ]
    }
  ]
}

Common mistakes to avoid

1. Forgetting to include all FOs. If you include only one FO in the request, every other FO is deleted.
2. Including fulfilled or cancelled items. They're preserved automatically; re-sending them may cause unexpected behaviour.
3. Not matching FO identifiers. Use fulfillment_order_id or partner_fulfillment_order_reference to match existing FOs.
4. Treating line items as a partial update. The line_items array replaces all pending items, so include every pending item you want to keep.

Order status restrictions

An order can be updated in any status except cancelled. That covers open, partially_allocated, allocated, processing, fulfilled, and closed.

Inventory impact

If inventory management is enabled, updating FOs automatically:

• Reserves inventory for new FO allocations.
• Releases inventory for removed FO allocations.
• Adjusts inventory for quantity changes.

Cancels an order and all its associated fulfillment orders.

Status requirements

An order can be cancelled only while it is still in an allocation phase:

• ✅ open: created but not yet allocated.
• ✅ partially_allocated: some items allocated to fulfillment locations.
• ✅ allocated: all items allocated to fulfillment locations.

Once fulfillment is under way or finished, cancellation is no longer allowed:

• ❌ processing: one or more fulfillment orders are being picked, packed, or shipped.
• ❌ fulfilled: all items have been fulfilled.
• ❌ closed: order is complete and closed.
• ❌ cancelled: order is already cancelled.

Cancellation effects

When an order is successfully cancelled:

• Every line item's quantity is set to 0 and its removed quantity is recorded.
• Every fulfillment order line item is marked cancelled.
• Reserved inventory is released back to stock.
• The order status is updated to cancelled.
• Webhooks fire to notify your systems.

Cancellation reason

Provide a cancellation_reason, one of:

• CUSTOMER_CANCELLATION: customer requested cancellation.
• AUTO_ALLOCATION_FAILED: automatic fulfillment allocation failed.
• INVENTORY_OUT_OF_STOCK: items are out of stock.
• STAFF_ERROR: staff made an error.
• PAYMENT_ISSUE: a payment problem occurred.
• OTHER: any other reason.

Anonymises the personal data on an order and propagates the redaction to dropoff fields on every linked shipment. This action is irreversible.

See also: Data Redaction, the full feature page covering order and shipment redaction scope, downstream sync, and GDPR compliance guidance.

Create multiple orders in a single request for batch processing.

Processing

Each order in the batch is processed independently:

• Valid orders are created.
• Invalid orders return error details.
• Processing continues even if some orders fail.

Limits

• Up to 20 orders per request by default (configurable per tenant). Chunk larger imports client-side.
• Each order follows the same validation as single order creation.

Duplicates

Bulk import is create-only; it does not upsert. A row whose partner_order_reference already exists in Carriyo, or that appears more than once within the batch, is rejected rather than updated. The successful rows in the same batch are unaffected.

Response

Returns one entry per input row, in the same order as the request. Each entry carries:

• result: SUCCESS when the order was created; otherwise an error code such as DUPLICATE or VALIDATION_ERROR.
• reason: human-readable detail when result is not SUCCESS.
• The full order object when result is SUCCESS.

Treat DUPLICATE as a no-op (the order is already in Carriyo) rather than a retryable failure.

Marks items in a fulfillment order as fulfilled and creates a shipment.

Line item status requirements

Only items in pending status (open or allocated) can be fulfilled:

• ✅ open - Item awaiting allocation
• ✅ allocated - Item assigned to a location
• ❌ fulfilled - Already fulfilled
• ❌ cancelled - Cannot be fulfilled
• ❌ closed - Cannot be fulfilled

Fulfillment process

When you fulfill an order, Carriyo:

1. Validates that the requested line items exist and are in a pending status.
2. Validates that the requested quantities don't exceed available quantities.
3. Creates a shipment (unless skip_shipping=true).
4. Marks line items as fulfilled with a unique fulfillment ID.
5. Updates the order status based on overall fulfillment progress.
6. Fires webhooks.

Line items (required)

Provide a line_items array specifying which items to fulfill. Each entry needs:

• id: matching an order line item.
• quantity: the quantity to fulfill, which must be ≤ the pending quantity.

Shipment creation

Control shipment creation with query parameters:

• create_draft_shipment=true: creates a draft shipment for review before carrier booking.
• skip_shipping=true: fulfills without creating any shipment (items auto-close).

Inventory impact

If inventory management is enabled with stock_reduction_timing = ON_ORDER_FULFILLED, both on_hand and reserved are reduced by the fulfilled quantity.

If shipping is not required (or skip_shipping=true), items are automatically set to closed.

Reverse a previous fulfillment, returning items to allocated status.

When to unfulfill

Use this endpoint when items were fulfilled in error, stock turns out to be unavailable after fulfillment, the fulfillment needs to move to another location, or a shipment was cancelled before pickup.

Request requirements

Provide fulfillment_ids, an array of the fulfillment IDs to reverse. Each must exist among the fulfillment order's fulfilled line items.

Effects

When you unfulfill, Carriyo:

1. Cancels associated shipments, if not already cancelled.
2. Returns line items to allocated status.
3. Clears the fulfillment ID, shipment IDs, and partner reference from the items.
4. Merges items that share the same ID and status.
5. Recalculates the order status.
6. Fires webhooks.

Inventory impact

If inventory management is enabled, on_hand is increased by the unfulfilled quantity, restoring stock.

Combine line items from one fulfillment order into another.

Merge process

Specify:

• Source: the fulfillment order (with specific line items) to merge from.
• Destination: the fulfillment order to merge into.

After merging, source line items move to the destination fulfillment order. If all items are moved, the source fulfillment order is removed. The order status is recalculated and webhooks fire.

Restrictions

The source and destination fulfillment orders:

• ❌ Cannot contain any fulfilled line items; only pending items can be merged.
• ✅ Must share the same location_id.
• ✅ Must share the same delivery_type (when specified).
• ✅ Must share the same delivery method.
• ❌ Cannot mix items where some require shipping and some don't.

Inventory impact

No inventory changes occur during a merge; items are only reorganised between fulfillment orders.

Split selected line items from a fulfillment order into a new fulfillment order. Use it to ship available items immediately while backordered items wait, to fulfill from multiple locations when only partial inventory exists, or to separate items with different shipping requirements.

Line item status requirements

Only items in a pending status can be split:

• ✅ open: can be split.
• ✅ allocated: can be split.
• ❌ fulfilled, cancelled, closed: cannot be split.

Split process

Specify:

• line_items (required): the items and quantities to move to the new FO.
• location_id (optional): a location for the split items. Defaults to the original FO's location.
• partner_fulfillment_order_reference (optional): your reference for the new FO.

After splitting, a new fulfillment order is created with a new fulfillment_order_id, inheriting delivery from the original. Split line items get status allocated when a location is set, otherwise open. The original FO's quantities are reduced (items are removed if their quantity reaches 0). The order status is recalculated and webhooks fire.

Inventory impact

No inventory changes occur during a split; items are only reorganised.

Create a shipment for items in a fulfillment order.

Line item status requirements

Items must be in allocated or fulfilled status:

• ✅ allocated: can be shipped.
• ✅ fulfilled: can be shipped (as an additional shipment).
• ❌ open: must be allocated first.
• ❌ cancelled, closed: cannot be shipped.

Request requirements

Provide line_items, the items to ship with their quantities.

Shipping process

When you ship, Carriyo:

1. Validates that the requested items are in allocated or fulfilled status.
2. Validates that the requested quantities don't exceed available quantities.
3. Creates a draft shipment in the Carriyo Shipping API.
4. Confirms the shipment with the carrier (unless create_draft_shipment=true).
5. Links the shipment ID to the specified line items.
6. Fires webhooks.

Shipment configuration

The request mirrors the Shipping API's create-shipment body. You can set the carrier account (or let automation rules decide), parcels, delivery instructions and scheduling, payment details including cash on delivery, and pre-booking information for externally booked shipments.

Draft shipments

Set create_draft_shipment=true to create a draft for review before booking with the carrier.

Inventory impact

No inventory changes occur here; inventory is managed during the fulfill and cancel operations.

Reassign a fulfillment order to a different location, for example to a location with available inventory or one closer to the customer.

Request requirements

Provide location_id, the new location's ID or code.

Location resolution

The value is resolved first by partner_location_id, then, if not found, by location_code for the merchant.

Effects

The fulfillment order's location_id is updated, the order status is recalculated, and webhooks fire.

Inventory impact

No inventory changes occur during a location update. Manage inventory reservations across the location change separately through the Inventory API if you need to.