> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Order

> Update an existing order

# Update Order

Updates an existing order. This is a **merchant-scoped** endpoint
authenticated with a merchant session (JWT). The same capability is also
available through the `update_order` MCP tool.

<Note>
  There is also `PATCH /orders/update-signle-order/:orderId` for lighter
  single-order field updates. Both accept the same body shape.
</Note>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.launchmystore.io/orders/ORDER_ID/update" \
    -H "Authorization: Bearer YOUR_MERCHANT_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "shipped",
      "courierName": "BlueDart",
      "trackingNumber": "TRK123456789",
      "notes": "Updated shipping instructions"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.launchmystore.io/orders/ORDER_ID/update', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_MERCHANT_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      status: 'shipped',
      courierName: 'BlueDart',
      trackingNumber: 'TRK123456789',
      notes: 'Updated shipping instructions'
    })
  });
  ```
</CodeGroup>

<Note>
  The route is `PUT /orders/update/:orderId` — the `orderId` path segment is
  the order's ID.
</Note>

## Path Parameters

<ParamField path="orderId" type="string" required>
  The unique order ID.
</ParamField>

## Body Parameters

The body is a partial order — every field is optional and only the supplied
fields are changed. Key fields:

<ParamField body="status" type="string">
  Order status. One of `pending`, `confirmed`, `shipped`, `delivered`,
  `canceled`, `returned`, `exchange`.
</ParamField>

<ParamField body="courierName" type="string">
  Carrier / courier name for the shipment.
</ParamField>

<ParamField body="trackingNumber" type="string">
  Tracking number for the shipment.
</ParamField>

<ParamField body="digitaldata" type="string">
  Digital delivery payload (keys / file URLs) for digital orders.
</ParamField>

<ParamField body="deliveryDate" type="string">
  Delivery date (ISO-8601).
</ParamField>

<ParamField body="restock" type="boolean">
  When `true` on a return/cancel update, stock is incremented back for every
  non-custom line item that had stock deducted (idempotent).
</ParamField>

<ParamField body="staffId" type="string">
  Staff member who performed the action (recorded for audit).
</ParamField>

<ParamField body="notes" type="string">
  Order notes.
</ParamField>

<ParamField body="products" type="array">
  Replacement order line items (each item carries `productId`, `quantity`,
  `varientId`, pricing, etc.).
</ParamField>

<ParamField body="clientName" type="string">
  Customer name for the shipping/contact details.
</ParamField>

<ParamField body="email" type="string">
  Customer email address.
</ParamField>

<ParamField body="mobileNumber" type="string">
  Customer phone number.
</ParamField>

<ParamField body="address" type="string">
  Street address.
</ParamField>

<ParamField body="city" type="string">
  City.
</ParamField>

<ParamField body="state" type="string">
  State / province.
</ParamField>

<ParamField body="country" type="string">
  Country.
</ParamField>

<ParamField body="pinCode" type="string">
  Postal / ZIP code.
</ParamField>

## Response

The platform returns the standard response envelope. `data` is the updated
order object.

<ResponseField name="status" type="integer">
  HTTP status code.
</ResponseField>

<ResponseField name="state" type="string">
  Result state (`success`, `error`).
</ResponseField>

<ResponseField name="message" type="string">
  Optional message (may be `null`).
</ResponseField>

<ResponseField name="data" type="object">
  The updated order object.
</ResponseField>

## Example Response

```json theme={null}
{
  "status": 200,
  "state": "success",
  "message": null,
  "data": {
    "orderId": "b8b0f1a2-3c4d-4e5f-9a0b-1c2d3e4f5a6b",
    "status": "shipped",
    "courierName": "BlueDart",
    "trackingNumber": "TRK123456789",
    "notes": "Updated shipping instructions",
    "shippedDate": "2024-01-25T16:00:00.000Z",
    "updatedAt": "2024-01-25T16:00:00.000Z"
  }
}
```

## Notes

* Status transitions are guarded: an order already `delivered` or `canceled`
  cannot have its status changed.
* Setting `paymentMethod` to a cash/offline method moves the order to `paid`.
* Use `restock: true` on a cancel/return to return inventory to stock.

## Error Codes

| Status | State   | Description                                                                    |
| ------ | ------- | ------------------------------------------------------------------------------ |
| `401`  | `error` | Invalid or missing authentication                                              |
| `404`  | `error` | Order with the specified ID does not exist                                     |
| `400`  | `error` | Invalid request body, or status change blocked (e.g. delivered/canceled order) |