# Hold and Restore Shipments

You can hold a shipment until a future date when it isn't ready to ship yet — for example, a pre-order that shouldn't leave the warehouse before its release date, or an order awaiting stock. A shipment on hold has the `on_hold` status, and you can't purchase a label for it while it's on hold.

On its `hold_until_date`, the shipment is released automatically: it returns to the `pending` status and its `hold_until_date` is cleared. To release a shipment earlier, restore it — restoring has the same effect.

Both operations work on a single shipment or on many shipments at once.

## Requirements

- The `shipment_id` of each shipment you want to hold or restore.
- For a hold, a `hold_until_date`.


## Hold Until Date

- It is a **date-only** value. You can send a plain `YYYY-MM-DD` date, and any time component you include is ignored.
- It must be **later than today**. Holding a shipment until today or an earlier date is rejected with a `400` response.
- Responses return the value at midnight, for example `"2026-10-15T00:00:00Z"`.
- Holding a shipment that is already on hold replaces the existing `hold_until_date`.


## Limitations

- You can hold or restore a maximum of **500 shipments** per request.
- A cancelled shipment or a shipment with a purchased label cannot be held. Holding it returns a `400` response.
- A shipment must be on hold before you can restore it. Restoring a shipment in any other status returns a `400` response.


## Partial Success for Multiple Shipments

The bulk endpoints process each shipment on its own. A shipment that cannot be held or restored — because it is not found, or because its status does not allow it — is reported in the `errors` array, and the remaining shipments are still processed.

- `200` — every shipment was processed. `shipment_ids` lists all of them.
- `207` — only some shipments were processed. `shipment_ids` lists the ones that were, and `errors` explains why the others were not.
- `404` — none of the shipments could be processed, and at least one of them was not found.
- `400` — none of the shipments could be processed because of their status.


When none of the shipments could be processed, the response body has the same shape, with an empty `shipment_ids` and the reasons in `errors`.

## Hold a Shipment

## Restore a Shipment

No request body is required.

## Hold Multiple Shipments

## Restore Multiple Shipments