Sign in
shipments

Hold a shipment

Changed on

Holds a shipment until a given date. A shipment on hold has the on_hold status, and you can't purchase a label for it while it's on hold. On the hold_until_date, the shipment is released automatically and returns to the pending status. Holding a shipment that is already on hold replaces the existing hold_until_date.

A cancelled shipment or a shipment with a purchased label cannot be held and returns a 400 response.

hold_until_date is a date-only value: any time component you send is ignored, and the date must be later than today.

To hold up to 500 shipments in one request, use Hold shipments.

put/v1/shipments/{shipment_id}/hold

Request

  • Base URL: https://api.shipengine.com
  • URL: https://api.shipengine.com/v1/shipments/{shipment_id}/hold
  • Auth: API key in header API-Key

Request body

hold_until_datestring date required

The date to hold the shipment until. This is a date-only value — you can send a plain YYYY-MM-DD date, and any time component is ignored. The date must be later than today.

Example request

{
  "hold_until_date": "2026-10-15"
}

Response

The request was a success.

shipment_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

hold_until_datestring date-time

The date the shipment is held until, returned at midnight

Example response

{
  "shipment_id": "se-28529731",
  "hold_until_date": "2026-10-15T00:00:00Z"
}

Changes

  • 020f57d6f5b8Revision changes
    • ▲

      the / response's property type changed from no type to object for status

    • ▲

      the / response's property type changed from no type to object for status

    • ▲

      the / response's property type changed from no type to object for status

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status

    • ○

      removed from the / response property allOf list for the response status

    • ○

      removed from the / response property allOf list for the response status

    • ○

      removed from the / response property allOf list for the response status

    • ○

      added the required property // to the response with the status

    • ○

      added the required property // to the response with the status

    • ○

      added the required property // to the response with the status

    • ○

      added the required property // to the response with the status

    • ○

      added the required property // to the response with the status

    • ○

      added the required property // to the response with the status

    • ○

      added the required property // to the response with the status

    • ○

      added the required property // to the response with the status

    • ○

      added the required property // to the response with the status

    • ○

      added the required property // to the response with the status

    • ○

      added the required property // to the response with the status

    • ○

      added the required property // to the response with the status

  • 87db9f1b6ab1Revision changes
    • ○

      endpoint added