***

title: Simulations
last-updated: 'February 24, 2026'
---------------------------------

## What Are Sandbox Simulations?

Sandbox Simulations let you:

* Test your integration with realistic, production-like data.
* Simulate actions that happen in a ShipBob facility (e.g., shipping or delivering an order).
* Spot and fix issues before they happen in real life.

Think of it as a practice run—everything works like the real thing, but no actual shipments are made.

<Note>
  If you haven't created a sandbox account or made your first API request, start with our [Sandbox Setup guide](/sandbox/setup).
</Note>

***

## Step 1: Set Up Your Sandbox Environment

Before running simulations, make sure your sandbox account is ready. Follow our [Sandbox Setup guide](/sandbox/setup) to:

* Sign up for a sandbox account
* Generate an API access token
* Use the correct base URLs
* Add payment methods and inventory (if needed)

Once setup is complete, continue with the steps below to simulate fulfillment events.

***

## Step 2: Understand How Simulations Work

Here’s the basic flow:

1. Send a request to a Simulation API endpoint.
2. Get a **simulation ID** in response.
3. The simulation runs in the background (it might take a little time to complete).

***

## Step 3: Pick an Action to Simulate

You can simulate the following:

* **Mark a Shipment/Order as Shipped**
* **Mark a Shipment/Order as Delivered**

To simulate other actions (e.g., returns, inventory changes), email [`techspecialists@shipbob.com`](mailto:techspecialists@shipbob.com).

***

## Step 4: Prepare Your Shipment

Ensure your shipment is eligible:

* **Inventory:** Product must have stock in Cicero (IL) or Moreno Valley (CA).
* **Packaging Preferences:** Set in Merchant App → Products → \[Your Product] → Packaging Preferences.
* **Customs Info:** Required for international shipments (set under Customs Information).
* **Shipment Status:** Must not be On-Hold, Exception, or Cancelled.
* **Fulfillment Center:** Inventory must exist in the selected location.
* **Test Payment Method:** Add dummy card in Dashboard → Payment Details using:
  * `4111 1111 1111 1111`, any name, email, expiration, and CVC.

***

## Step 5: Run a Simulation

**Endpoint**

```http
POST https://sandbox-api.shipbob.com/2025-07/simulate/shipment
```

**Authorization:** Bearer \{token}\
**Header:** `shipbob_channel_id` (integer)

**Request Body Schema**

```json
{
  "shipment_id": 11471145,
  "simulation": {
    "action": "ShipOrder",
    "delay": null,
    "next": {
      "action": "DeliverOrder",
      "delay": 10
    }
  }
}
```

| Field         | Description                                                                |
| ------------- | -------------------------------------------------------------------------- |
| `shipment_id` | Required. The ID of the shipment to simulate.                              |
| `action`      | Required. `"ShipOrder"` or `"DeliverOrder"`.                               |
| `delay`       | Optional. Time in minutes (1–2880) to wait before running the action.      |
| `next`        | Optional. A nested object for the next simulation action (up to 5 levels). |

***

**Example Requests**

**Mark as Shipped:**

```json
{
  "shipment_id": 11471145,
  "simulation": {
    "action": "ShipOrder"
  }
}
```

**Mark as Delivered:**

```json
{
  "shipment_id": 11471145,
  "simulation": {
    "action": "DeliverOrder"
  }
}
```

**Ship then Deliver with Delay:**

```json
{
  "shipment_id": 11471145,
  "simulation": {
    "action": "ShipOrder",
    "delay": 5,
    "next": {
      "action": "DeliverOrder",
      "delay": 10
    }
  }
}
```

***

## Step 6: Check Simulation Status

Use the `simulation_id` returned from your request to check its progress.

**Endpoint**

```http
GET https://sandbox-api.shipbob.com/2025-07/simulate/status/{simulation_id}
```

**Authorization:** Bearer \{token}

**Response (200 OK)**

```json
{
  "simulation_id": "d1cdb...ef3",
  "entity_id": "11471145",
  "entity_type": "shipment",
  "simulation": {
    "action": "ShipOrder",
    "status": "Success",
    "message": "ShipOrder",
    "schedule_time": "2025-06-01T14:00:00Z",
    "next": {
      "action": "DeliverOrder",
      "status": "Pending",
      "message": "DeliverOrder",
      "schedule_time": "2025-06-01T14:10:00Z"
    }
  }
}
```

| Field           | Description                                                |
| --------------- | ---------------------------------------------------------- |
| `status`        | One of `Success`, `Failed`, `Pending`, or `Skipped`.       |
| `schedule_time` | Time the action is scheduled for (if delay was set).       |
| `next`          | Nested action status (if multiple actions were simulated). |

***

## Simulation API Reference

| Endpoint                        | Method | Description                           |
| ------------------------------- | ------ | ------------------------------------- |
| `/2025-07/simulate/shipment`    | POST   | Register a simulation for a shipment. |
| `/2025-07/simulate/status/{id}` | GET    | Get the status of a simulation.       |

***

## FAQ

<AccordionGroup>
  <Accordion title="What statuses can I simulate?">
    * Shipped
    * Delivered
  </Accordion>

  <Accordion title="Can I simulate an order in any status?">
    No. The order cannot be On-Hold, Exception, or Cancelled.
  </Accordion>

  <Accordion title="Can I simulate multiple actions?">
    Yes, up to 5 nested actions.
  </Accordion>

  <Accordion title="What happens if I set a delay longer than 2 days?">
    The delay will be capped at 2880 minutes (2 days).
  </Accordion>

  <Accordion title="Can I simulate in the production environment?">
    No. Simulations are only supported in the Sandbox.
  </Accordion>

  <Accordion title="Do I need inventory to simulate a shipment?">
    Yes. Inventory must be available in a supported fulfillment center.
  </Accordion>
</AccordionGroup>