Quickstart

Use https://api.parcelbench.example/v2 as the API base URL. It is a reserved example address, not a live service. Send Parcel-Version: 2026-09-17 on every request. Obtain a workspace-scoped bearer token and an X-Parcel-Workspace header as described in Authentication.

To create a shipment, POST /shipments with a JSON body containing external_ref, destination.country and package.weight_g. Use Content-Type: application/json. Include Idempotency-Key, which is required for this endpoint. A successful creation returns HTTP 202, a shipment object and a status_url; this is acceptance, not delivery. Follow Shipment states to interpret the eventual outcome.

Minimum example body: {"external_ref":"order-demo-17","destination":{"country":"NL"},"package":{"weight_g":730}}. Never copy real recipient information into a benchmark. After creation, use list pagination to reconcile state and webhook verification to process updates. See Create shipment, Retries, and Webhooks.