Updates an existing order with the specified changes. This endpoint allows partial updates to order details, line items, and fulfillment orders.

⚠️ Important Warning

This endpoint can be dangerous if not used correctly. The fulfillment orders (fulfillment_orders) field behaves as a full replacement - any fulfillment order not included in the request will be permanently removed.

---

Update Behavior

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
• shipping_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. Ensure you include all line items you want to keep.

Fulfillment Orders (Full Replacement with Preservation Rules)

If fulfillment_orders is provided:

• Any FO not included will be REMOVED - Always include all FOs you want to keep
• FOs are matched by fulfillment_order_id or partner_fulfillment_order_reference
• New FOs (without matching ID) will be created with a new fulfillment_order_id

---

Fulfillment Order Line Items - Critical Rules

When updating FO line items, you must follow these rules:

What to Include

Only pass line items with pending statuses:

• open - Items not yet allocated
• allocated - Items allocated but not fulfilled

What is Automatically Preserved

The system automatically preserves line items with terminal statuses:

• fulfilled - Items that have been fulfilled (will be added back automatically)
• cancelled - Items that have been cancelled (will be added back automatically)
• closed - Items that are closed (will be added back automatically)

You do NOT need to include fulfilled, cancelled, or closed line items in your request - they will be preserved automatically.

---

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: FO will have 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 only include one FO in the request, all other FOs will be deleted
2. Including fulfilled/cancelled items: Don't include them - they're preserved automatically. Including them may cause unexpected behavior
3. Not matching FO identifiers: Always use either fulfillment_order_id or partner_fulfillment_order_reference to match existing FOs
4. Partial line item updates: The line_items array replaces all pending items, so include all pending items you want to keep

---

Order Status Restrictions

Orders can only be updated when their status allows it:

• ✅ open, partially_allocated, allocated, partially_fulfilled, fulfilled, closed - Can be updated
• ❌ cancelled - Cannot be updated

---

Inventory Impact

If inventory management is enabled, updating FOs will automatically:

• Reserve inventory for new FO allocations
• Release inventory for removed FO allocations
• Adjust inventory for quantity changes