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

# Patch one native shipment without skipping lifecycle guards.

> Updated shipment

> [!WARNING]
>
> **Confirm your deployment before running this request.** This page describes an API contract;
> a published reference does not establish hosted availability. Check the dated
> [host report](/api-reference/hosts) and obtain your deployment URL and credentials.
> Replace the example host if your provisioned service uses a different URL.

### Path parameters

**id** `string` *required*

Shipment ID (UUID)

### Request body

`UpdateShipmentRequest`

**carrier** `string,null`

**dimensions** `string,null`

**estimated\_delivery** `string,null (date-time)`

**expected\_version** `integer,null (int32)`

**notes** `string,null`

**recipient\_email** `string,null`

**recipient\_name** `string,null`

**recipient\_phone** `string,null`

**shipping\_address** `string,null`

**shipping\_cost** `string,null`

Exact decimal string in the order's currency.

**status** `string,null`

Native lifecycle status; `cancelled` is not accepted by this endpoint.

**tracking\_number** `string,null`

**weight\_kg** `string,null`

Exact decimal string, in kilograms.

### Response

`ShipmentResponse`

**carrier** `string` *required*

**created\_at** `string (date-time)` *required*

**delivered\_at** `string,null (date-time)`

**dimensions** `string,null`

**estimated\_delivery** `string,null (date-time)`

**id** `string (uuid)` *required*

**items** `ShipmentItemResponse[]`

Manifest assignments; not proof of order fulfillment or inventory reservation.

**ShipmentItemResponse**

**id** `string (uuid)` *required*

**name** `string` *required*

**order\_item\_id** `string,null (uuid)`

**product\_id** `string,null (uuid)`

**quantity** `integer (int32)` *required*

**shipment\_id** `string (uuid)` *required*

**sku** `string` *required*

**notes** `string,null`

**order\_id** `string (uuid)` *required*

**recipient\_email** `string,null`

**recipient\_name** `string` *required*

**recipient\_phone** `string,null`

**shipment\_number** `string` *required*

**shipped\_at** `string,null (date-time)`

**shipping\_address** `string` *required*

**shipping\_cost** `string,null`

**shipping\_method** `string` *required*

**status** `string` *required*

**tracking\_number** `string,null`

**tracking\_url** `string,null`

**updated\_at** `string (date-time)` *required*

**version** `integer (int32)` *required*

**weight\_kg** `string,null`

### Status codes

| Code | Meaning |
| - | - |
| `200` | Updated shipment |
| `404` | Shipment not found |
| `409` | Stale shipment version |
| `422` | Invalid fields or lifecycle transition |

### Using this contract

Read the [source OpenAPI document](/spec/stateset-icommerce.json) for declared schemas and alternatives.
This page also includes documented corrections from the [spec overlays](https://github.com/stateset/docs/tree/main/spec/overlays).
Example IDs and values are illustrative; replace them with records from your workspace.

```bash cURL theme={null}
curl --silent --show-error --fail-with-body --request PATCH \
  --url 'https://api.stateset.com/api/v1/shipments/{id}' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "carrier": "UPS",
  "dimensions": "string",
  "estimated_delivery": "2026-08-31T14:22:05Z",
  "expected_version": 1,
  "notes": "Two-person tent, green — replacement for damaged pole set.",
  "recipient_email": "string",
  "recipient_name": "Ada Lovelace",
  "recipient_phone": "+1 415 555 0142",
  "shipping_address": "548 Market St",
  "shipping_cost": "8.00",
  "status": "pending",
  "tracking_number": "1Z999AA10123456784",
  "weight_kg": "string"
}'
```

```json 200 theme={null}
{
  "carrier": "UPS",
  "created_at": "2026-08-31T14:22:05Z",
  "delivered_at": "2026-08-31T14:22:05Z",
  "dimensions": "string",
  "estimated_delivery": "2026-08-31T14:22:05Z",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Two-Person Tent",
      "order_item_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": 2,
      "shipment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "sku": "SKU-TENT-2P-GRN"
    }
  ],
  "notes": "Two-person tent, green — replacement for damaged pole set.",
  "order_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "recipient_email": "string",
  "recipient_name": "Ada Lovelace",
  "recipient_phone": "+1 415 555 0142",
  "shipment_number": "string",
  "shipped_at": "2026-08-31T14:22:05Z",
  "shipping_address": "548 Market St",
  "shipping_cost": "8.00",
  "shipping_method": "ground",
  "status": "pending",
  "tracking_number": "1Z999AA10123456784",
  "tracking_url": "string",
  "updated_at": "2026-08-31T14:22:05Z",
  "version": 1,
  "weight_kg": "string"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.