> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crbtrack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox Mode

> Test your integration safely without creating real shipments

## Overview

The sandbox environment lets you test your integration without:

* Creating real shipments
* Incurring shipping costs
* Affecting production data

<Note>
  All sandbox operations are isolated. Nothing created in sandbox will appear in production.
</Note>

## 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

<Steps>
  <Step title="Login to Dashboard">
    Go to [dashboard.crbtrack.com](https://dashboard.crbtrack.com)
  </Step>

  <Step title="Navigate to API Keys">
    Click **Settings** → **API Keys**
  </Step>

  <Step title="Generate Sandbox Key">
    Click **Generate Sandbox Key** (or create a key and select "Sandbox" environment)
  </Step>
</Steps>

## Test Scenarios

The sandbox supports special tracking number prefixes to simulate different scenarios:

<Tabs>
  <Tab title="Successful Delivery">
    **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.
  </Tab>

  <Tab title="Failed Delivery">
    **Prefix**: `SB-FAIL-*`

    Simulates delivery failure.

    ```
    ORDERED → LABEL_GENERATED → IN_TRANSIT → 
    DELIVERY_ATTEMPTED → DELIVERY_FAILED
    ```
  </Tab>

  <Tab title="Customs Hold">
    **Prefix**: `SB-CUSTOMS-*`

    Simulates a parcel held at customs.

    ```
    ORDERED → LABEL_GENERATED → CUSTOMS_CLEARANCE → 
    CUSTOMS_HOLD → (waits 1 hour) → CUSTOMS_CLEARANCE → IN_TRANSIT
    ```
  </Tab>

  <Tab title="Return to Sender">
    **Prefix**: `SB-RTS-*`

    Simulates return to sender.

    ```
    ORDERED → LABEL_GENERATED → IN_TRANSIT → 
    DELIVERY_ATTEMPTED → RETURN_TO_SENDER
    ```
  </Tab>
</Tabs>

## Example: Testing Different Scenarios

### Create a successful delivery test

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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

<Warning>
  Some features are limited in sandbox mode:
</Warning>

| 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:

<Steps>
  <Step title="Generate Production Key">
    Create a new API key with "Production" environment
  </Step>

  <Step title="Update Base URL">
    Change from `sandbox.crbtrack.com` to `api.crbtrack.com`
  </Step>

  <Step title="Update Webhook URL">
    Configure your production webhook endpoint
  </Step>

  <Step title="Replace API Key">
    Update your environment variables with the production key (`pk_live_...`)
  </Step>

  <Step title="Test a Real Order">
    Create a small test order to verify everything works
  </Step>
</Steps>

## Sandbox Data Cleanup

Sandbox data is automatically purged after 30 days. You can also manually clear your sandbox data:

```bash theme={null}
curl -X POST https://sandbox.crbtrack.com/api/v1/sandbox/reset \
  -H "X-API-Key: <YOUR_SANDBOX_KEY>"
```

<Warning>
  This permanently deletes all your sandbox orders, manifests, and tracking data. This action cannot be undone.
</Warning>