Sandbox Mode

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

Go to dashboard.crbtrack.com

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

Status updates occur every 5 minutes.

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

Configure Sandbox Webhooks

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.

Getting Started

Reference

Overview

Sandbox vs Production

Getting a Sandbox Key

Test Scenarios

Example: Testing Different Scenarios

Create a successful delivery test

Create a customs hold test

Webhook Testing

Configure Sandbox Webhooks

Sample Sandbox Webhook Payload

Sandbox Limitations

Transitioning to Production

Sandbox Data Cleanup

​Overview

​Sandbox vs Production

​Getting a Sandbox Key

​Test Scenarios

​Example: Testing Different Scenarios

​Create a successful delivery test

​Create a customs hold test

​Webhook Testing

​Configure Sandbox Webhooks

​Sample Sandbox Webhook Payload

​Sandbox Limitations

​Transitioning to Production

​Sandbox Data Cleanup

Overview

Sandbox vs Production

Getting a Sandbox Key

Test Scenarios

Example: Testing Different Scenarios

Create a successful delivery test

Create a customs hold test

Webhook Testing

Configure Sandbox Webhooks

Sample Sandbox Webhook Payload

Sandbox Limitations

Transitioning to Production

Sandbox Data Cleanup