{"templateId":"markdown","versions":[{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/shipping/shipments-hold-restore","default":false,"active":false,"folderId":"58c9a61d"},{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/docs/shipping/shipments-hold-restore","default":true,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/shipping/shipments-hold-restore","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml","oas-apis/@shipstation-v2/openapi.yaml":"oas-apis/@shipstation-v2/openapi.yaml"},"props":{"metadata":{"markdoc":{"tagList":["openapi-code-sample"]},"type":"markdown"},"seo":{"title":"Hold and Restore Shipments","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"hold-and-restore-shipments","__idx":0},"children":["Hold and Restore Shipments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_hold"]}," status, and you can't purchase a label for it while it's on hold."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hold_until_date"]},", the shipment is released automatically: it returns to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}," status and its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hold_until_date"]}," is cleared. To release a shipment earlier, restore it — restoring has the same effect."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both operations work on a single shipment or on many shipments at once."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"requirements","__idx":1},"children":["Requirements"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]}," of each shipment you want to hold or restore."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For a hold, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hold_until_date"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hold-until-date","__idx":2},"children":["Hold Until Date"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["It is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["date-only"]}," value. You can send a plain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]}," date, and any time component you include is ignored."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["It must be ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["later than today"]},". Holding a shipment until today or an earlier date is rejected with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Responses return the value at midnight, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"2026-10-15T00:00:00Z\""]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Holding a shipment that is already on hold replaces the existing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hold_until_date"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"limitations","__idx":3},"children":["Limitations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You can hold or restore a maximum of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["500 shipments"]}," per request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A cancelled shipment or a shipment with a purchased label cannot be held. Holding it returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A shipment must be on hold before you can restore it. Restoring a shipment in any other status returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," response."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"partial-success-for-multiple-shipments","__idx":4},"children":["Partial Success for Multiple Shipments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array, and the remaining shipments are still processed."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," — every shipment was processed. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_ids"]}," lists all of them."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["207"]}," — only some shipments were processed. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_ids"]}," lists the ones that were, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," explains why the others were not."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," — none of the shipments could be processed, and at least one of them was not found."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," — none of the shipments could be processed because of their status."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When none of the shipments could be processed, the response body has the same shape, with an empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_ids"]}," and the reasons in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hold-a-shipment","__idx":5},"children":["Hold a Shipment"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/@shipstation-v2/openapi.yaml","operationId":"hold_shipment","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"restore-a-shipment","__idx":6},"children":["Restore a Shipment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No request body is required."]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/@shipstation-v2/openapi.yaml","operationId":"restore_shipment","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hold-multiple-shipments","__idx":7},"children":["Hold Multiple Shipments"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/@shipstation-v2/openapi.yaml","operationId":"hold_shipments","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"restore-multiple-shipments","__idx":8},"children":["Restore Multiple Shipments"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/@shipstation-v2/openapi.yaml","operationId":"restore_shipments","parameters":{},"environments":{}},"children":[]}]},"headings":[{"value":"Hold and Restore Shipments","id":"hold-and-restore-shipments","depth":1},{"value":"Requirements","id":"requirements","depth":2},{"value":"Hold Until Date","id":"hold-until-date","depth":2},{"value":"Limitations","id":"limitations","depth":2},{"value":"Partial Success for Multiple Shipments","id":"partial-success-for-multiple-shipments","depth":2},{"value":"Hold a Shipment","id":"hold-a-shipment","depth":2},{"value":"Restore a Shipment","id":"restore-a-shipment","depth":2},{"value":"Hold Multiple Shipments","id":"hold-multiple-shipments","depth":2},{"value":"Restore Multiple Shipments","id":"restore-multiple-shipments","depth":2}],"frontmatter":{"slug":"/hold-and-restore-shipments","seo":{"title":"Hold and Restore Shipments"}},"lastModified":"2026-10-02T10:17:19.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/hold-and-restore-shipments","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}