Fulfillments (shipments)

A fulfillment is a shipment against a FulfillmentOrder. You can create several per FO to ship in batches.

Create a fulfillment

POST /fulfillments

{ "fulfillment": {
    "line_items_by_fulfillment_order": [
      { "fulfillment_order_id": "fo_…",
        "fulfillment_order_line_items": [ { "id": "foli_…", "quantity": 1 } ] } ],
    "tracking_info": { "company": "UPS", "number": "1Z…",
      "url": "https://www.ups.com/track?tracknum=1Z…" },
    "notify_customer": true } }

Returns the created fulfillment (status, tracking_*, line items). We fire fulfillments/create, and orders/fulfilled once the FO is fully shipped.

Partial shipments

Omit fulfillment_order_line_items → ships all remaining quantity on the FO.
Send a quantity less than remaining_quantity → ships part; the FO stays in_progress and you can ship the rest later.

Multiple tracking numbers

Use the plural fields instead of the singular ones (don’t mix them):

"tracking_info": { "company": "UPS", "numbers": ["1Z1","1Z2"],
                   "urls": ["https://…/1Z1","https://…/1Z2"] }

If you omit url, we derive the tracking URL from a recognized company + number.

Update tracking

POST /fulfillments/{id}/update_tracking

{ "tracking_info": { "company": "UPS", "number": "1Z…", "url": "https://…" }, "notify_customer": true }

Fires fulfillments/update.

Cancel a shipment

POST /fulfillments/{id}/cancel Marks the shipment cancelled and re-opens the quantity on its FulfillmentOrder so it can be fulfilled again.

Statuses

status (Fulfillment): pending · open · success · cancelled · error · failure.
display_status: granular carrier state — label_printed · in_transit · out_for_delivery · delivered · …

​Create a fulfillment

​Partial shipments

​Multiple tracking numbers

​Update tracking

​Cancel a shipment

​Statuses