Skip to Content
FastracDocs

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

SandboxProduction
API hosthttps://sandbox-api.fastrac.examplehttps://api.fastrac.example
Token URLhttps://sandbox-auth.fastrac.cc/realms/users/protocol/openid-connect/tokenhttps://api.fastrac.cc/realms/users/protocol/openid-connect/token
client_idYour keyIdYour keyId (the same)
client_secretsandboxSecretsecret
DataSeparate. Orders, shipments, balance and webhook settings don't carry over.Your real data.
BalanceA separate sandbox balance.Your real balance.
ShipmentsFor testing only. Don't hand real parcels over for sandbox airway bills.Real shipments.
Status changesSimulate them with simulate-status.Come from the courier.
simulate-status endpointAvailableReturns 403

Tokens are not interchangeable: a sandbox token is rejected by production, and the other way round.

Set up the sandbox

  1. 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"
  2. 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.

  3. 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

  1. Search the origin and destination regions.
  2. Request rates and pick one.
  3. Create an order with its shippingRateCode. Note the shipment code (SHP-…) and airwayBill.
  4. Call simulate-status to move the shipment along.
  5. 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" }'
InboundResponse
{
  "statusCode": 200,
  "message": "Shipment status simulated successfully."
}

Status values

statusShipment becomesWebhook eventEffect on sandbox data
DRIVER_ASSIGNEDNo changeshipment.pending_pickupSample driver details are added (name, phone, licence plate).
TRANSITIN_TRANSITshipment.in_transitA history entry is added.
DELIVEREDDELIVEREDshipment.deliveredThe shipment is completed, as after a real delivery.
CANCELLEDCANCELLEDNone (cancel with POST /b2b/shipments/cancel/{shipmentCode} to receive shipment.cancelled)The amount paid for the shipment is refunded to your sandbox balance.
RTSRTS_DELIVEREDshipment.rts_billed if a return fee appliesThe shipment is completed as returned to sender. A return fee is charged to your sandbox balance if the courier charges one.
AIRWAYBILL_UPDATEDNo changeshipment.airway_bill_updatedThe airway bill is replaced with a test value starting with SIM-.
PRICE_CHANGEDNo changeshipment.price_changedWebhook only, with sample values: price_before 10000, price_after 15000, delta 5000. Your balance is not changed.
WEIGHT_CHANGEDNo changeshipment.measurement_changedWebhook only, with sample before and after measurements.
RTS_BILLEDNo changeshipment.rts_billedWebhook 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 DELIVERED or RTS_DELIVERED shipment 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

StatusMessageCause
400Shipment SHP-… not found.The shipment code doesn't exist in the sandbox.
400status must be one of the following values: …status is missing or not in the table above.
403Simulate 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.

ScenarioHowCheck that your system…
Happy pathDRIVER_ASSIGNED → TRANSIT → DELIVEREDshows the driver, each status, and marks the shipment delivered.
Cancellation by courierCANCELLEDmarks the shipment cancelled and expects the refund in balance logs.
Cancellation by youPOST /b2b/shipments/cancel/{code}handles the response and the shipment.cancelled webhook.
Return to senderTRANSIT → RTStreats the shipment as returned, not delivered.
Airway bill changedAIRWAYBILL_UPDATEDstores the new airway bill and tracking link.
Price adjustmentPRICE_CHANGEDrecords the extra charge for reconciliation.
ReweighWEIGHT_CHANGEDrecords the new measurement.
Return feeRTS_BILLEDrecords the return fee.
Expired rateWait past validUntil, then create the orderasks for a new rate instead of retrying.
Insufficient balanceBook while your sandbox balance is too lowshows a clear message and doesn't retry.
Duplicate webhookReplay the same event to your endpointignores it, using x-webhook-id.

Next steps

Was this page helpful?

On this page