Create shipment

POST /v2/shipments creates a shipment asynchronously. Required headers are Authorization, X-Parcel-Workspace, Parcel-Version: 2026-09-17, Content-Type: application/json and Idempotency-Key. Required scope: shipments:write.

The body requires external_ref (a nonempty string), destination.country (two uppercase country-code letters), and package.weight_g (integer 1 through 28000). HTTP 202 returns {"shipment":{"id":"shp_example","state":"QUEUED"},"status_url":"/v2/shipments/shp_example"}. HTTP 202 does not mean that a carrier accepted or delivered the parcel.

HTTP 422 invalid_weight means the body failed validation and must be corrected. HTTP 409 idempotency_conflict means this key was already used with a different request body; do not retry the changed payload with that key. For a timed-out connection, reuse the original key and exactly the same body. See Idempotency and Retries.

The API does not accept a mass field or lowercase country codes. Legacy field names belong only to v1.