Orders

Orders is where a customer's purchase becomes work for your fulfillment locations. Carriyo accepts the order from your storefront, OMS, or connectors. It allocates the order across your locations, splits or merges where needed, and hands the result to Shipping for booking and execution.

You can also push Orders into Carriyo purely for visibility, keeping allocation and inventory in your existing OMS, and triggering shipping through the API when your system marks the order as fulfilled. The Order entity is the same; how much of its lifecycle Carriyo manages is up to you.

What Carriyo's order management does

• Ingest from anywhere. API, connectors (Shopify, Magento, WooCommerce, SFCC, custom), file import, or Dashboard creation. All sources land as the same Order object.
• Allocate across locations. Decide which fulfillment location (warehouse, store, dark store) ships which line: manually, via rules, or by a connector that's already decided.
• Split and merge. Multi-location orders split into one shipment per pickup; same-location lines can be merged into a single shipment.
• Pre-booked passthrough. When orders are already booked upstream, Carriyo just tracks them. No double-booking.
• Cross-border data. Carry HS codes, item values, and party details through to the shipment so customs paperwork is correct.

The model

Three objects matter at this stage: the Order, the fulfillment order, and the Shipment.

• An Order represents the customer's purchase: the lines they bought and the address they're shipping to. One Order per customer-facing transaction.
• A fulfillment order is one allocation decision: a subset of the order's lines plus a chosen pickup location. Each Order produces one or more fulfillment orders.
• Each fulfillment order ships as one or more Shipments: the parcels handed to a carrier. Most ship as a single Shipment; multiple are supported when one fulfillment order needs to split across consignments.

For a deeper diagram of how these objects relate, see Domain model.

Integration shapes

Order integrations come in three shapes. The right shape depends on how much of the post-checkout flow Carriyo manages.

1. End-to-end

Carriyo runs the full post-checkout flow, including picking and packing through the Fulfillment App. Inventory is held in Carriyo, and allocation decisions are made against it.

Best for: clients who want Carriyo as their operations system of record, end to end.

2. External WMS

Orders, inventory, and shipping run in Carriyo; a WMS handles picking and packing. Carriyo receives fulfillment events from the WMS, and those events trigger shipment booking and label generation.

Best for: clients with a deeply integrated WMS who still need OMS and inventory in their commerce stack.

3. Order passthrough

OMS, inventory, and fulfillment all run outside Carriyo. Orders still flow into Carriyo so allocation and fulfillment events can be recorded. Once a fulfillment event arrives, Carriyo books the shipment, generates the label, and runs the post-purchase flow. Carriyo doesn't need to track stock in this shape.

Best for: clients with an external OMS who want Carriyo's shipping orchestration and post-purchase experience.

Cross-border data

Cross-border orders need richer customs data: HS codes, item values, country of origin, exporter and importer details, incoterms. Carriyo carries these through Order → Shipment so the carrier generates a clean commercial invoice. This is orthogonal to the three shapes above; it can layer onto any of them.

Returns

Returns layer on top of any shape. A return request always references the originating order via partner_order_reference. Carriyo uses that reference to locate the associated shipments, whether or not an Order entity exists in Carriyo. When the Order does exist, the return links to it directly.

How orders relate to other objects

Customer purchase
       │
       ▼
   Order  ◀── ingested from storefront / API / connector
       │
       │  allocated by location, split if needed
       ▼
Fulfillment Order(s)  ◀── one per (location, line subset)
       │
       │  carrier picked, label generated
       ▼
   Shipment(s)
       │
       │  status events flow back
       ▼
Customer-facing tracking + notifications

How it fits with other modules

• Shipping. Every fulfillment order produces a Shipment when it's ready to book. Shipping takes over from there.
• Inventory. Allocation decisions often lean on stock visibility per location. Inventory feeds allocation.
• Post-purchase CX. Customer notifications and tracking pages react to events on the order and its shipments.
• Returns. Return requests are scoped to an order's lines.
• Account model. Orders are scoped per merchant within a tenant.
• Data redaction. Per-customer anonymization for GDPR right-to-erasure requests.