> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer-stage.shipbob.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-stage.shipbob.dev/_mcp/server. # Simulations ## 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. If you haven't created a sandbox account or made your first API request, start with our [Sandbox Setup guide](/sandbox/setup). *** ## 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 There are two ways to run simulations: **API** 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). **UI Terminal** 1. Open the Simulation Terminal from the sandbox dashboard. 2. Pick a workflow (e.g., `fulfill-order`, `receive-wro`, `adjust-inventory`). 3. Follow the interactive prompts to provide inputs and advance through stages. *** ## Step 3: Pick an Action to Simulate **Using the API**, you can simulate: * **Mark a Shipment/Order as Shipped** * **Mark a Shipment/Order as Delivered** **Using the UI Terminal**, the following workflows are available: * **Receive WRO** — Simulate receiving a warehouse receiving order. * **Fulfill Order** — Simulate shipping and delivering an order. * **Adjust Inventory** — Simulate inventory adjustments. To simulate other actions, email [`support@shipbob.com`](mailto:support@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/2026-01/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 } } } ``` You can also run simulations directly from the **ShipBob Simulation Terminal** — a built-in terminal panel available in the sandbox environment. **Opening the Terminal** Press `Ctrl` + `` ` `` to open or close the terminal panel. You can also collapse, expand, or go fullscreen using the controls in the panel header. ![Simulation Terminal on the Orders page](https://files.buildwithfern.com/ship-stage.docs.buildwithfern.com/477d582a1c13c6c63a428908de8de09b84126dd06dcaa4a0831a445abe4c7f21/docs/assets/images/Terminal_initial.png) **Running a Workflow** 1. Type `list` to see all available workflows: | # | Workflow | Stages | Inputs | | - | ------------------ | ------ | ------ | | 1 | `receive-wro` | 5 | 1 | | 2 | `fulfill-order` | 5 | 1 | | 3 | `adjust-inventory` | 2 | 1 | 2. Start a workflow by typing its ID. The terminal will prompt you for any required inputs: ```bash fulfill-order ``` 3. To run specific stages of a workflow, use the `--from` and `--to` flags: ```bash fulfill-order --from 2 --to 4 ``` Workflows are currently available on the **Orders**, **Inventory Status**, and **Receiving Orders** pages. ![Simulation Terminal showing available workflows and commands](https://files.buildwithfern.com/ship-stage.docs.buildwithfern.com/621ca79cc00a4cd0d91a14937a25541f1f0f555b7d6dbc5d88d1d906888844b0/docs/assets/images/Terminal_commands.png) **Available Commands** | Command | Description | | ------------------------------------------ | ----------------------------------------------------------------------------- | | `help [command]` | List all commands or describe a specific one. | | `list` | Display available workflows. | | `` | Start a workflow interactively, collecting missing inputs via prompts. | | ` --from --to ` | Start a workflow with a specific stage range. | | `status [runId]` | Show the current state of a run, or the active run if no `runId` is provided. | | `cancel [runId]` | Cancel a running workflow, or the active run if no `runId` is provided. | | `clear` | Clear the terminal output. | The Simulation Terminal is only available in the **sandbox (stage) environment**. It is not accessible in production. *** ## 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/2026-01/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" } } } ``` **Response Fields** * `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 | | ------------------------------- | ------ | ------------------------------------- | | `/2026-01/simulate/shipment` | POST | Register a simulation for a shipment. | | `/2026-01/simulate/status/{id}` | GET | Get the status of a simulation. | *** ## FAQ **Using the API**, you can simulate: * **Mark as Shipped** — Mark a shipment/order as shipped. * **Mark as Delivered** — Mark a shipment/order as delivered. **Using the UI Terminal**, the following workflows are supported: * **Receive WRO** — Simulate receiving a warehouse receiving order (5 stages). * **Fulfill Order** — Simulate shipping and delivering an order (5 stages). * **Adjust Inventory** — Simulate inventory adjustments (2 stages). No. The order cannot be On-Hold, Exception, or Cancelled. Yes, up to 5 nested actions. The delay will be capped at 2880 minutes (2 days). No. Simulations are only supported in the Sandbox. Yes. Inventory must be available in a supported fulfillment center.