Sandbox & simulator

Build and test your integration without drivers, recipients or money. Use a test token and every shipment you create is a sandbox shipment that you move along yourself.

Try it in four steps

Make a test token (atk_test_…) in Settings → Developers. Test tokens only see and create sandbox shipments, even in a company that is already live.
Create and confirm a shipment as in the quickstart. Drafts are not simulated: confirming prices the shipment and gives it its tracking number.
Move it one step at a time with the simulator (below). Each step sends the same events and webhooks a real delivery would.
Check what your system did: your webhook endpoint got "livemode": false messages, and GET /v1/shipments/{id} shows the status and history.

Simulator

POST /v1/sandbox/shipments/{id}/advance moves a sandbox shipment to the status in to, through the same state machine real deliveries use. The answer is the shipment.

curl -s "$ANTIVIO/v1/sandbox/shipments/$SHIPMENT/advance" \
  -H "Authorization: Bearer $ANTIVIO_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" -d '{"to": "picked_up"}'

// antivio() is the helper from the quickstart.
const moved = await antivio("POST", `/v1/sandbox/shipments/${shipmentId}/advance`, {
  to: "picked_up",
});
console.log(moved.status); // "picked_up"

# antivio() is the helper from the quickstart.
moved = antivio("POST", f"/v1/sandbox/shipments/{shipment_id}/advance", {"to": "picked_up"})
print(moved["status"])  # "picked_up"

POST /v1/sandbox/shipments/{id}/advance
Authorization: Bearer atk_test_…
Idempotency-Key: 3f1c…
Content-Type: application/json

{ "to": "picked_up" }

Where the simulator can move a shipment

Delivery

ready
pickup_assigned
picked_up
at_hubhub service levels
out_for_delivery
delivered

Failed attempt

out_for_delivery
attempt_failed
out_for_deliveryattempts left

attempt_failed
return_in_transitattempts used up
returned

Problems

…any open status
exception
closed_exception

Every move the rules allow:

From	`to`
`ready`	`pickup_assigned`, `at_hub` (customer drop-off, hub service levels)
`pickup_assigned`	`picked_up`
`picked_up`	`out_for_delivery` (direct service levels), `at_hub` (hub service levels)
`at_hub`	`out_for_delivery`, `return_in_transit` (attempts used up)
`out_for_delivery`	`delivered`, `attempt_failed`
`attempt_failed`	`out_for_delivery` (attempts left), `at_hub`, `return_in_transit` (attempts used up)
`return_in_transit`	`returned`
any open status	`exception`
`exception`	`closed_exception`

A step the rules do not allow answers 409 with the state machine's code (for example shipment.hub_required or shipment.attempts_remaining).
Live tokens get 403 sandbox.live_token; live shipments 409 sandbox.live_shipment.
Only the shipment moves (its status, attempts and history); driver tasks stay as they were.

What is real in the sandbox

A test token only sees and creates sandbox shipments. The database enforces it, not just the API.
A company still under review creates sandbox shipments with any token.
Sandbox shipments are free, are not offered to drivers and send nothing to recipients. Everything else is real: validation, prices, tracking numbers, labels, events and webhooks.
Webhook messages about sandbox shipments carry "livemode": false and go to test endpoints only.
A test token reads the shared address book but only changes or archives the locations it created, and never sees live labels or live webhook endpoints.