Overview
The sandbox environment lets you test your integration without:
- Creating real shipments
- Incurring shipping costs
- Affecting production data
All sandbox operations are isolated. Nothing created in sandbox will appear in production.
Sandbox vs Production
| Feature | Sandbox | Production |
|---|
| Base URL | sandbox.crbtrack.com | api.crbtrack.com |
| API Key Prefix | pk_test_ | pk_live_ |
| Tracking Numbers | Start with SB | Real carrier numbers |
| Labels | Marked “SANDBOX” | Production labels |
| Webhooks | Simulated events | Real events |
| Rate Limits | 100 req/sec (relaxed) | 50 req/sec |
| Data Persistence | 30 days | Permanent |
Getting a Sandbox Key
Navigate to API Keys
Click Settings → API Keys
Generate Sandbox Key
Click Generate Sandbox Key (or create a key and select “Sandbox” environment)
Test Scenarios
The sandbox supports special tracking number prefixes to simulate different scenarios:
Successful Delivery
Failed Delivery
Customs Hold
Return to Sender
Prefix: SB-SUCCESS-*Simulates a parcel that progresses through all statuses to successful delivery.ORDERED → LABEL_GENERATED → CUSTOMS_CLEARANCE →
IN_TRANSIT → OUT_FOR_DELIVERY → DELIVERED
Prefix: SB-FAIL-*Simulates delivery failure.ORDERED → LABEL_GENERATED → IN_TRANSIT →
DELIVERY_ATTEMPTED → DELIVERY_FAILED
Prefix: SB-CUSTOMS-*Simulates a parcel held at customs.ORDERED → LABEL_GENERATED → CUSTOMS_CLEARANCE →
CUSTOMS_HOLD → (waits 1 hour) → CUSTOMS_CLEARANCE → IN_TRANSIT
Prefix: SB-RTS-*Simulates return to sender.ORDERED → LABEL_GENERATED → IN_TRANSIT →
DELIVERY_ATTEMPTED → RETURN_TO_SENDER
Example: Testing Different Scenarios
Create a successful delivery test
curl -X POST https://sandbox.crbtrack.com/api/v1/orders/create \
-H "X-API-Key: <YOUR_SANDBOX_KEY>" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "test-success-001",
"trackingNumber": "SB-SUCCESS-12345",
"sender": { ... },
"receiver": { ... },
"parcelDetails": { ... }
}'
Create a customs hold test
curl -X POST https://sandbox.crbtrack.com/api/v1/orders/create \
-H "X-API-Key: <YOUR_SANDBOX_KEY>" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "test-customs-001",
"trackingNumber": "SB-CUSTOMS-67890",
"sender": { ... },
"receiver": { ... },
"parcelDetails": { ... }
}'
Webhook Testing
Sandbox webhooks behave the same as production but:
- Fire immediately (no real carrier delay)
- Include
"environment": "sandbox" in the payload
- Use your configured sandbox webhook URL
In the dashboard, set a separate webhook URL for sandbox:
Sandbox Webhook URL: https://your-server.com/webhooks/crossborderly-sandbox
Sample Sandbox Webhook Payload
{
"event": "parcel.status_changed",
"environment": "sandbox",
"timestamp": "2024-12-21T10:30:00Z",
"data": {
"trackingNumber": "SB-SUCCESS-12345",
"previousStatus": "IN_TRANSIT",
"newStatus": "OUT_FOR_DELIVERY",
"location": "Guayaquil, EC"
}
}
Sandbox Limitations
Some features are limited in sandbox mode:
| Feature | Sandbox Behavior |
|---|
| Carrier Integration | Simulated (no real carrier calls) |
| Label Printing | Works, but labels marked “SANDBOX” |
| Customs Validation | Simplified validation rules |
| Data Retention | 30 days (then deleted) |
| Carrier Tracking | Simulated status progression |
Transitioning to Production
When you’re ready to go live:
Generate Production Key
Create a new API key with “Production” environment
Update Base URL
Change from sandbox.crbtrack.com to api.crbtrack.com
Update Webhook URL
Configure your production webhook endpoint
Replace API Key
Update your environment variables with the production key (pk_live_...)
Test a Real Order
Create a small test order to verify everything works
Sandbox Data Cleanup
Sandbox data is automatically purged after 30 days. You can also manually clear your sandbox data:
curl -X POST https://sandbox.crbtrack.com/api/v1/sandbox/reset \
-H "X-API-Key: <YOUR_SANDBOX_KEY>"
This permanently deletes all your sandbox orders, manifests, and tracking data. This action cannot be undone.
