Request Shipment of a parcel(s)

This is the call that actually sets a delivery in motion. The parcels must already exist — see Create a parcel — and you must say which shipping type to use.

Request

curl --request POST \
  --url https://logistics.api.{{BASE_ENV_URL}}/v1/parcels/ship \
  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "parcel_ids": ["3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"],
    "shipping_type_id": "express_default",
    "pickup_time": "2021-12-02T10:12:07.753Z"
  }'

Field	Required	Notes
`parcel_ids`	Yes	The platform IDs returned when you created the parcels. Several parcels shipped together become one delivery.
`shipping_type_id`	Yes	From Available shipping types, and one that is active at the pickup location of these parcels. The id identifies the shipping type itself and does not vary by region; what varies is where it is active, so check the list for that location. Echo it back exactly as returned: it is opaque, a readable name in sandbox and a UUID in production.
`pickup_time`	No	RFC 3339. Only applicable to the `express` modality.

Response

202 — the request is accepted and is being processed. The shipment is not complete at this point; it has been queued. From here the parcel moves through the states described in Parcels life cycle, and the way to follow it is Track parcels or, better, a notification webhook.

When it fails

Status	Meaning
`400`	A field failed validation.
`401`	Missing or invalid access token.
`403`	The parcel is not yours, or that shipping type is not available to your account.
`404`	The parcel or the shipping type does not exist.
`409`	One or more parcels are in a state that does not allow shipping — for example already shipped, or cancelled.
`422`	The shipment cannot be created: pickup and dropoff too far apart, the parcel does not fit any available vehicle, the delivery window is missing or spans more than one day, or a parcel's location information is incomplete.

📘
409 almost always means "already shipped"
Requesting the shipment of a parcel twice is the most common cause. Check the parcel's state with Track parcels before retrying.

Updated 2 days ago

Did this page help you?