# Change the status of a shipment

```http
PUT https://secure.yoprint.com/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/shipment/{id}/status
```

- API version: v2
- Operation ID: `v2_public_sales_order_shipment_change_status`
- Section: Shipping › [Shipments](https://developer.yoprint.com/reference/shipments.md)
- Web page: https://developer.yoprint.com/reference/shipments/v2-sales-order-shipment-change-status/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Moves a shipment to another shipment status. `status_id` comes from the team's shipment statuses. `{hash_id}` is the order's `id`; `{id}` is the shipment's `id`.

`notify_customer` matters only for Shopify shipments moving to a final status: it is then required, and Shopify creates the fulfillment and tells the customer when it is true. For other shipments it has no effect.

The answer is the shipment in the older shape, with its `status` and `items`, plus `previous_status_id` and `previous_status` (the status before this call).

## Permission

Any member of the team.

## Business rules

- The order must be published: "Publish this order before changing shipment status."
- The status must be a shipment status of the team.

## Side effects

- Emails the team about the change and sends the `shipment.status_changed` webhook, only when the status really changes: picking the shipment's current status sends neither.
- For a Shopify shipment moving to a final status, creates the fulfillment in Shopify, then emails the team and sends the webhook.
- Customer Portal pages the order's customer has open refresh (also when the status didn't change).

## Path parameters

- `team_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.
- `hash_id` (string, required): The sales order's or quote's `id` (a hash id). The `ord_` unique key and the order number do not work here. Example `V4keXwwxMQyXw7`.
- `id` (string, required): The shipment's `id` (a hash id). Example `qAKg4jO63uFqjs`.

## Request body

Content type `application/json`, required.

Fields:

- `status_id` (string, required): A shipment status id.
- `notify_customer` (boolean | null, optional): Shopify shipments only; see above.

### Example request

```bash
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/shipment/qAKg4jO63uFqjs/status' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "status_id": "lziIhzgc0acXFc"
  }'
```

## Response

`200` Successful response.

Fields:

- `data` (object, required): A shipment, in the older shape (app/Transformers/ShipmentTransformer.php, which always includes `status` and `items`).
  - `id` (string, required)
  - `status_id` (string, required)
  - `delivery_notes` (string | null, optional)
  - `delivery_total` (integer | number | string | null, optional): Older shipping total. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
  - `items` (array of objects, optional): Shipment lines, in the older shape.
  - `order_id` (string, optional)
  - `order_scoped_id` (string, optional)
  - `previous_status` (object | null, optional): A status, as the status operations return it.
    - `color` (string, required): A hex color, such as `#2196f3`.
    - `customer_label` (string, required): What customers see in the customer portal. When none is set: `Pending` for `start`, `In Progress` for `in_progress` and `pre_production`, `Completed` for `end`.
    - `id` (string, required)
    - `label` (string, required): The status name people see.
    - `position` (integer, required): Sort order within its list, lowest first.
    - `role` (string, required): Which list the status belongs to: `order`, `quote`, `job`, `shipment`, `purchase_order`, `pipeline` or `customer_message`.
    - `trashed` (boolean, required): true for a deleted status.
    - `type` (string, required): `start` is the first status of its list and `end` the last; `pre_production` and `in_progress` are the ones in between. One of: `"start"`, `"pre_production"`, `"in_progress"`, `"end"`.
    - `pipeline_id` (string, optional): The task preset, for `pipeline` statuses only; absent for other roles.
  - `previous_status_id` (string | null, optional): The status before this call.
  - `scoped_id` (string, optional)
  - `shipping_address_id` (string | null, optional)
  - `status` (object | null, optional): A status, as the status operations return it. Same fields as `data.previous_status` above.
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "data": {
    "delivery_total": 0,
    "id": "qAKg4jO63uFqjs",
    "order_id": "V4keXwwxMQyXw7",
    "order_scoped_id": "SO1001",
    "previous_status": {
      "color": "#2196f3",
      "customer_label": "In Progress",
      "id": "rfc8TboAnPpGAS",
      "label": "Packing",
      "position": 2,
      "role": "shipment",
      "trashed": false,
      "type": "in_progress"
    },
    "previous_status_id": "rfc8TboAnPpGAS",
    "scoped_id": "SHIP-1001",
    "shipping_address_id": "RNG2OuYC20YzXs",
    "status": {
      "color": "#4caf50",
      "customer_label": "Completed",
      "id": "lziIhzgc0acXFc",
      "label": "Shipped",
      "position": 3,
      "role": "shipment",
      "trashed": false,
      "type": "end"
    },
    "status_id": "lziIhzgc0acXFc"
  },
  "status": 200,
  "success": true
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
- `403` You are not allowed to do this. `api_access_not_in_plan`: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only `{"message": "Insufficient Permission"}`. Other refusals use the error envelope, with `unauthorized` or `user_is_not_authorized`.
- `404` Not found. `page_not_found`: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. `code: null`, with a message that starts "No query results for": there is no record with that id.
  - When: The status or shipment is not found. Fix: Use ids from this team and order.
- `422` The request was refused and changed nothing. `validation_failed` lists what to fix in `error.fields`; other codes name a business rule, explained in `error.message`. A few checks answer with only `{"message": "..."}`. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer `connect_timeout` ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
  - When: A draft order, or a Shopify shipment moving to its final status without `notify_customer` (`shopify_terminal_status_requires_fulfillment`). Fix: Publish the order, or send `notify_customer`.

## Related

- [List shipment statuses](https://developer.yoprint.com/reference/statuses/v1-status-list-shipment.md): `GET /v1/api/store/{team_slug}/setting/status/shipment`
- [List the shipments of a sales order](https://developer.yoprint.com/reference/shipments/v2-sales-order-shipment-index-for-order.md): `GET /v2/api/store/{team_slug}/v2/sales_order/{unique_key}/shipment`