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

curl -i -X PUT \
  https://api.shipstation.com/v2/shipments/se-28529731/hold \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "hold_until_date": "2026-10-15"
  }'

Restore a Shipment

No request body is required.

curl -i -X PUT \
  https://api.shipstation.com/v2/shipments/se-28529731/restore \
  -H 'api-key: YOUR_API_KEY_HERE'

Hold Multiple Shipments

curl -i -X POST \
  https://api.shipstation.com/v2/shipments/hold \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "shipment_ids": [
      "se-202902255",
      "se-202902256"
    ],
    "hold_until_date": "2026-10-15"
  }'

Restore Multiple Shipments

curl -i -X POST \
  https://api.shipstation.com/v2/shipments/restore \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "shipment_ids": [
      "se-202902255",
      "se-202902256"
    ]
  }'