# Update an order shipment

Sets the delivery company, tracking number and stage of a paid physical order. The merchant and the customer see them on the order.

```http
PATCH https://larm.sa/stores/{storeId}/v1/orders/{id}/shipment
```

Scope: `orders.shipment:write`

Send `status` every time; `carrier`, `tracking_number`, `tracking_url` and `label_url` keep their last value when omitted. `label_url` is the shipping label the merchant prints. Only this reply returns it: other apps and the customer never see it. The first `shipped` or `out_for_delivery` notifies the customer, and `delivered` completes the order. See [Delivery companies](/guides/delivery-companies).

## Path parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |


## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | yes | The shipment stage. delivered completes the order and tells the customer it arrived. One of: `shipped`, `out_for_delivery`, `delivery_attempted`, `delivered`, `returned`. |
| `carrier` | string | no | The delivery company name. Required on the first update of an order that has no delivery option. |
| `tracking_number` | string | no |  |
| `tracking_url` | string (uri) | no | An https link the customer opens. |
| `label_url` | string (uri) | no | An https link to the shipping label the merchant prints. The customer does not see it. |


## Response

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes |  |
| `data.order_id` | string | no |  |
| `data.status` | string | no | The shipment stage. delivered completes the order and tells the customer it arrived. One of: `shipped`, `out_for_delivery`, `delivery_attempted`, `delivered`, `returned`. |
| `data.carrier` | string | no |  |
| `data.tracking_number` | string \| null | no |  |
| `data.tracking_url` | string \| null | no |  |
| `data.label_url` | string \| null | no |  |
| `data.updated_at` | string (date-time) | no |  |
| `execution` | object | no | Who executed the request: the app, version, installation and store. Field names here are camelCase. |
| `execution.appId` | string (uuid) | no |  |
| `execution.versionId` | string (uuid) | no |  |
| `execution.installationId` | string (uuid) | no |  |
| `execution.storeId` | string (uuid) | no |  |
| `execution.requestId` | string (uuid) | no |  |
| `execution.generation` | integer | no |  |
| `execution.routeEpoch` | integer | no |  |
| `execution.appAuthEpoch` | integer | no |  |
| `execution.grantRevision` | integer | no |  |
| `meta` | object | yes |  |
| `meta.request_id` | string (uuid) | no | The request ID; include it in any support request. |


## Example request

```bash
curl -X PATCH "https://larm.sa/stores/$STORE_ID/v1/orders/200123/shipment" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "out_for_delivery", "carrier": "Fast Courier", "tracking_number": "FC-20145", "tracking_url": "https://track.example.com/FC-20145", "label_url": "https://labels.example.com/FC-20145.pdf" }'
```


## Example response (200)

```json
{
  "data": {
    "order_id": "200123",
    "status": "out_for_delivery",
    "carrier": "Fast Courier",
    "tracking_number": "FC-20145",
    "tracking_url": "https://track.example.com/FC-20145",
    "label_url": "https://labels.example.com/FC-20145.pdf",
    "updated_at": "2026-11-02T10:04:00.000Z"
  },
  "execution": {
    "appId": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
    "versionId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "installationId": "c7e4a1f2-6b3d-4e8a-9c05-1d2f3a4b5c6d",
    "storeId": "5b1d7a62-0c4e-4f38-9a51-2e7b3c9d8f10",
    "requestId": "3f0c2b8e-7a51-4c1e-9d0a-5b6f1e2d4c3a",
    "generation": 1,
    "routeEpoch": 4,
    "appAuthEpoch": 1,
    "grantRevision": 2
  },
  "meta": {
    "request_id": "3f0c2b8e-7a51-4c1e-9d0a-5b6f1e2d4c3a"
  }
}
```


## Errors

| HTTP | Code | Meaning |
|---|---|---|
| 404 | `RESOURCE_NOT_FOUND` | The ID does not exist in this store. |
| 409 | `SHIPMENT_OWNED_ELSEWHERE` | The merchant or another app owns this shipment. |
| 409 | `SHIPPING_ORDER_NOT_ELIGIBLE` | The order is unpaid, cancelled, refunded, delivered, or has nothing to ship. |
| 409 | `SHIPPING_LARM_LABEL_EXISTS` | The order already has a Larm shipping label. |
| 409 | `SHIPPING_SELF_UNAVAILABLE` | This store ships through Larm only. |
| 422 | `INVALID_SHIPMENT_STATUS` | Unknown stage. |
| 422 | `SHIPMENT_CARRIER_REQUIRED` | No delivery company on the order or in the request. |
| 422 | `INVALID_TRACKING_URL` | The tracking link is not https. |
| 422 | `INVALID_LABEL_URL` | The label link is not https. |
| 403 | `SCOPE_REQUIRED` | The token does not carry the required scope. |
| 503 | `APPS_SCOPE_RUNTIME_NOT_READY` | The resource is not enabled on this merchant's store yet. |