Place an order with multiple fulfillment orders

Most orders let Carriyo's allocation engine decide which lines ship from which location. But if you run your own OMS and have already made that decision, you can supply the split directly. Pass an explicit fulfillment_orders array on the create call and Carriyo persists your split instead of allocating for you.

Scenario

A US merchant receives an order for two items. Their OMS has inventory visibility and has already decided the split: the keyboard ships from the New Jersey warehouse, the monitor from the Los Angeles warehouse. They send Carriyo one order carrying two fulfillment orders, one per location.

Prerequisites

• API credentials: see Getting started.
• Two locations configured, referenced here by their partner_location_code.
• The split already computed in your OMS. Carriyo does not re-allocate fulfillment orders you supply explicitly.

Step 1, decide the line-item ids

When you supply your own fulfillment orders, each FO references the order's line items by id. Set that id yourself on each line item so you can reference it from the FO. (If you omit it, Carriyo generates one, but then you can't reference it in the same request.)

Here the two lines get ids line-kbd and line-mon.

Step 2, create the order with explicit fulfillment orders

curl -X POST 'https://api.carriyo.com/orders' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'tenant-id: YOUR_TENANT_ID' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant": "ACME",
    "partner_order_reference": "YOUR_ORDER_REF",
    "order_date": "2026-05-12T14:05:00.000Z",
    "sales_channel": "web",
    "payment": {
      "currency": "USD",
      "order_total": 489.98
    },
    "customer": {
      "contact_name": "Alex Chen",
      "contact_email": "alex.chen@example.com",
      "contact_phone": "+12125550100"
    },
    "line_items": [
      {
        "id": "line-kbd",
        "sku": "KBD-MECH-87",
        "description": "Mechanical keyboard, 87-key",
        "quantity": 1,
        "unit_price": 139.99
      },
      {
        "id": "line-mon",
        "sku": "MON-27-4K",
        "description": "27-inch 4K monitor",
        "quantity": 1,
        "unit_price": 349.99
      }
    ],
    "fulfillment_orders": [
      {
        "partner_fulfillment_order_reference": "YOUR_ORDER_REF-NJ",
        "location_id": "NJ-WH-01",
        "delivery_method": "DELIVERY",
        "delivery_address": {
          "contact_name": "Alex Chen",
          "contact_phone": "+12125550100",
          "address1": "350 5th Avenue",
          "city": "New York",
          "state": "NY",
          "country": "US",
          "postcode": "10118"
        },
        "line_items": [
          { "id": "line-kbd", "quantity": 1 }
        ]
      },
      {
        "partner_fulfillment_order_reference": "YOUR_ORDER_REF-LA",
        "location_id": "CA-WH-02",
        "delivery_method": "DELIVERY",
        "delivery_address": {
          "contact_name": "Alex Chen",
          "contact_phone": "+12125550100",
          "address1": "350 5th Avenue",
          "city": "New York",
          "state": "NY",
          "country": "US",
          "postcode": "10118"
        },
        "line_items": [
          { "id": "line-mon", "quantity": 1 }
        ]
      }
    ]
  }'

Notes on the payload:

• merchant is your Carriyo merchant id (the uppercase identifier created with the merchant). It is not the merchant's display name.
• location_id on each FO accepts either the location's partner_location_code (used here) or Carriyo's internal location id.
• partner_fulfillment_order_reference is required on each supplied FO. It's your own reference for that FO, useful for reconciling against your OMS.
• Each FO's line_items[].id references a line item id from the order's top-level line_items.
• The delivery method, address, and schedule live on each FO. The top-level delivery_* convenience fields only apply to auto-allocated orders; since you're supplying FOs, set those fields per FO.

Step 3, read the response

Carriyo persists your split as-is. The order comes back already in allocated, with the two fulfillment orders you supplied, each at its assigned location:

{
  "order_id": "OMP7782ABCDEF",
  "merchant": "ACME",
  "partner_order_reference": "YOUR_ORDER_REF",
  "status": "allocated",
  "payment": { "currency": "USD", "order_total": 489.98 },
  "line_items": [
    { "id": "line-kbd", "sku": "KBD-MECH-87", "quantity": 1, "unit_price": 139.99 },
    { "id": "line-mon", "sku": "MON-27-4K", "quantity": 1, "unit_price": 349.99 }
  ],
  "fulfillment_orders": [
    {
      "fulfillment_order_id": "FOMP7782NJ001",
      "partner_fulfillment_order_reference": "YOUR_ORDER_REF-NJ",
      "location_id": "NJ-WH-01",
      "status": "allocated",
      "delivery_method": "DELIVERY",
      "line_items": [
        { "id": "line-kbd", "quantity": 1, "status": "allocated" }
      ]
    },
    {
      "fulfillment_order_id": "FOMP7782LA001",
      "partner_fulfillment_order_reference": "YOUR_ORDER_REF-LA",
      "location_id": "CA-WH-02",
      "status": "allocated",
      "line_items": [
        { "id": "line-mon", "quantity": 1, "status": "allocated" }
      ]
    }
  ]
}

Each FO is now independently fulfillable and shippable. From here, fulfill each FO and book its shipment as usual.

Auto-allocate vs supply your own

	Auto-allocate	Supply fulfillment_orders
Who decides the location split	Carriyo's allocation engine	Your OMS
When to use	Carriyo holds inventory/location rules	You already know the split
fulfillment_orders on create	omitted	provided
Delivery fields	top-level convenience fields	set per FO

If you want Carriyo to make the decision instead, omit fulfillment_orders and see Place an order with a delivery option.

Pitfalls

• Set line-item id yourself when supplying FOs. An FO line item references the order line item by id. If you let Carriyo generate the ids, you can't reference them in the same create call.
• Supplied FOs are not re-allocated. Carriyo trusts your split. If a location can't actually fulfill its lines, that surfaces later (at fulfillment), not as a re-allocation.
• Every supplied line must belong to an FO. A line item left out of all fulfillment orders has nothing to fulfill it.