Use the sandbox
Build and test against the sandbox, and simulate delivery, cancellation, returns and adjustments.
- Product
- APIShipping Engine API
- Section
- Get started
- Reading time
- 5 min read
The sandbox is a separate copy of Shipping Engine for building and testing. It has the same API as production, its own data and balance, and one extra endpoint that moves a shipment to any status so you can test every path without waiting for a courier.
Sandbox and production
| Sandbox | Production | |
|---|---|---|
| API host | https://sandbox-api.fastrac.example | https://api.fastrac.example |
| Token URL | https://sandbox-auth.fastrac.cc/realms/users/protocol/openid-connect/token | https://api.fastrac.cc/realms/users/protocol/openid-connect/token |
client_id | Your keyId | Your keyId (the same) |
client_secret | sandboxSecret | secret |
| Data | Separate. Orders, shipments, balance and webhook settings don't carry over. | Your real data. |
| Balance | A separate sandbox balance. | Your real balance. |
| Shipments | For testing only. Don't hand real parcels over for sandbox airway bills. | Real shipments. |
| Status changes | Simulate them with simulate-status. | Come from the courier. |
simulate-status endpoint | Available | Returns 403 |
Tokens are not interchangeable: a sandbox token is rejected by production, and the other way round.
Set up the sandbox
Point your app at the sandbox
Use the sandbox host, token URL and
sandboxSecret. Keep them in configuration so that going live is only a configuration change:export FASTRAC_API="https://sandbox-api.fastrac.example" export FASTRAC_TOKEN_URL="https://sandbox-auth.fastrac.cc/realms/users/protocol/openid-connect/token" export FASTRAC_CLIENT_ID="your-key-id" export FASTRAC_CLIENT_SECRET="your-sandbox-secret"Check your sandbox balance
Orders are paid from your sandbox balance, just as in production. Check it with
GET /b2b/user-balance. If it is too low to create orders, contact Fastrac support.Register a sandbox webhook (optional)
Webhook settings are per environment. Register your test endpoint in the sandbox with
POST /b2b/webhook/setWebhook. See Testing webhooks.
Test end to end
- Search the origin and destination regions.
- Request rates and pick one.
- Create an order with its
shippingRateCode. Note the shipmentcode(SHP-…) andairwayBill. - Call
simulate-statusto move the shipment along. - Check what your system saw: the webhook events,
GET /b2b/shipments/{code}/details, and your balance logs.
The Quickstart walks through steps 1 to 4 with copy-paste commands.
Simulate a status change
POST /b2b/shipments/{shipmentCode}/simulate-status
acts as if the courier had reported an update. It needs the CANCEL_ORDER permission.
curl -s -X POST "$FASTRAC_API/b2b/shipments/SHP-261120-K7Q2MX/simulate-status" \
-H "Authorization: Bearer $FASTRAC_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "status": "DELIVERED" }'{
"statusCode": 200,
"message": "Shipment status simulated successfully."
}Status values
status | Shipment becomes | Webhook event | Effect on sandbox data |
|---|---|---|---|
DRIVER_ASSIGNED | No change | shipment.pending_pickup | Sample driver details are added (name, phone, licence plate). |
TRANSIT | IN_TRANSIT | shipment.in_transit | A history entry is added. |
DELIVERED | DELIVERED | shipment.delivered | The shipment is completed, as after a real delivery. |
CANCELLED | CANCELLED | None (cancel with POST /b2b/shipments/cancel/{shipmentCode} to receive shipment.cancelled) | The amount paid for the shipment is refunded to your sandbox balance. |
RTS | RTS_DELIVERED | shipment.rts_billed if a return fee applies | The shipment is completed as returned to sender. A return fee is charged to your sandbox balance if the courier charges one. |
AIRWAYBILL_UPDATED | No change | shipment.airway_bill_updated | The airway bill is replaced with a test value starting with SIM-. |
PRICE_CHANGED | No change | shipment.price_changed | Webhook only, with sample values: price_before 10000, price_after 15000, delta 5000. Your balance is not changed. |
WEIGHT_CHANGED | No change | shipment.measurement_changed | Webhook only, with sample before and after measurements. |
RTS_BILLED | No change | shipment.rts_billed | Webhook only, with a sample rts_fee of 15000. Your balance is not changed. |
Rules that still apply
- Simulate only after the shipment has an
airwayBill. Without one, nothing changes. - Simulations follow the normal status rules. A
DELIVEREDorRTS_DELIVEREDshipment doesn't change again, and a returned shipment never goes back to a normal status. See Order and shipment lifecycle. - Webhooks are sent only if your sandbox endpoint is registered, verified and subscribed to the event.
Errors
| Status | Message | Cause |
|---|---|---|
400 | Shipment SHP-… not found. | The shipment code doesn't exist in the sandbox. |
400 | status must be one of the following values: … | status is missing or not in the table above. |
403 | Simulate shipment status is not allowed in PRODUCTION environment. | You called the production host. |
Test scenarios
Run these before going live. Each one checks a path your code must handle.
| Scenario | How | Check that your system… |
|---|---|---|
| Happy path | DRIVER_ASSIGNED → TRANSIT → DELIVERED | shows the driver, each status, and marks the shipment delivered. |
| Cancellation by courier | CANCELLED | marks the shipment cancelled and expects the refund in balance logs. |
| Cancellation by you | POST /b2b/shipments/cancel/{code} | handles the response and the shipment.cancelled webhook. |
| Return to sender | TRANSIT → RTS | treats the shipment as returned, not delivered. |
| Airway bill changed | AIRWAYBILL_UPDATED | stores the new airway bill and tracking link. |
| Price adjustment | PRICE_CHANGED | records the extra charge for reconciliation. |
| Reweigh | WEIGHT_CHANGED | records the new measurement. |
| Return fee | RTS_BILLED | records the return fee. |
| Expired rate | Wait past validUntil, then create the order | asks for a new rate instead of retrying. |
| Insufficient balance | Book while your sandbox balance is too low | shows a clear message and doesn't retry. |
| Duplicate webhook | Replay the same event to your endpoint | ignores it, using x-webhook-id. |
Next steps
Was this page helpful?