Orders

The Order object represents a customer order containing one or more items to be fulfilled. Orders serve as the foundation for the fulfillment process in Carriyo.

Key Concepts

Order Structure

Each order contains:

  • Customer Information : customer (contact + address), billing_address , and language/sales channel
  • Line Items : Products ordered with quantities and prices
  • Fulfillment Orders : Groups of line items assigned to specific locations; each FO holds delivery method , delivery type , and delivery or customer-collection address and schedule
  • Payment Information : Currency, order total, and any payment-on-delivery amount

Delivery Methods

A fulfillment order's delivery_method controls how the customer receives the items:

  • DELIVERY — Standard delivery to the customer's address. Uses delivery_address and delivery_schedule .
  • COLLECTION — Customer collects the order from a specified location (e.g., a store, locker, or pickup point). Uses customer_collection_address and customer_collection_schedule .
  • DIGITAL — No physical delivery; the order is fulfilled digitally.

When creating an order, you can set delivery_method, addresses, and schedules either at the top level (which propagates to all auto-allocated fulfillment orders) or per fulfillment order in the fulfillment_orders array.

Order Status

Orders progress through the following statuses:

  • open — Order created, awaiting allocation
  • partially_allocated — Some line items have been allocated to a fulfillment location
  • allocated — All line items are allocated and ready to be fulfilled
  • processing — One or more fulfillment orders are being processed (picked, packed, shipped, or partially fulfilled)
  • fulfilled — All items have been fulfilled
  • cancelled — Order has been cancelled
  • closed — Order is complete and closed

Reference Keys

Orders can be retrieved using:

  • order_id — Carriyo's unique identifier for the order
  • partner_order_reference — Your system's order reference (pass key=partner_order_reference as a query parameter)

This allows flexible integration with your existing order management systems.

Change history and system logs

  • Change logs — List transactional audit records for the order (who/what changed and when).
  • System logs — Record and query integration traffic metadata (correlation id, request/response summary, stored payloads via pre-signed URLs when applicable).

Privacy

  • Redact — Remove or mask personal data on an order while retaining the record structure for operational needs.

Shipment-driven updates

  • Shipment status update — Post a shipment payload (as from the Shipping API or webhooks) so Carriyo can align order and fulfillment state—for example when a shipment reaches delivered and eligible line items can be auto-closed.

Fulfillment Orders

When an order is created, Carriyo automatically generates fulfillment orders based on:

  • Inventory availability across locations
  • Location-based allocation rules
  • Explicit fulfillment order specifications in the request

Each fulfillment order represents items to be shipped from a single location, with its own delivery method, address, and schedule.