> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer-dev.shipbob.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-dev.shipbob.dev/_mcp/server.

# Sandbox Simulations

ShipBob's **Simulation Terminal** is now available in all sandbox accounts. It lets you simulate the full lifecycle of ShipBob operations — fulfillment, receiving, and inventory adjustments — directly from the merchant dashboard, without needing real warehouse activity.

This is the fastest way to test your integration end-to-end and build confidence before going live.

![Simulation Terminal on the Orders page](https://files.buildwithfern.com/ship-dev.docs.buildwithfern.com/940b84ddf6646382f75ee18e85994d9db1c8ab0ae8771dda7a4634cf1cc8af66/docs/assets/images/simulations-1.png)

***

## Before You Start

Make sure the following conditions are met before running a simulation.

* **Packaging Preferences:** Set via API or in Merchant App → Products → \[Your Product] → Packaging Preferences.
* **Customs Info:** Required if testing international shipments (set under Customs Information).
* **Shipment Status:** Must not be On-Hold, Exception, or Cancelled.
* **Test Payment Method:** Add a dummy card in Dashboard → Payment Details using `4111 1111 1111 1111`, any name, email, expiration, and CVC.

- **FC Access:** Your account must have access to the spoke FC location where the WRO will be received.

* **Bin Stock:** Inventory must be present on a bin in the FC allocated to your account.

***

## Accessing the Simulation Terminal

The Simulation Terminal is embedded at the bottom of the Orders, Inventory Status, and Warehouse Receiving Orders pages in your sandbox account [here](https://webstage.shipbob.dev/App/Merchant/#/order-shipment-management/orders).

1. Log in to your sandbox account.
2. Look for the **Simulations** bar pinned to the bottom of the screen.
3. Click it to expand, or toggle it with `Ctrl` + `M`.
4. Use the icons in the panel header to **toggle fullscreen**, **switch the theme** (dark/light), and **minimize** or **close** the terminal.

The terminal shows "Connected" when it's active and ready to accept commands. Dark mode is enabled by default — click the sun/moon icon in the header to switch themes. Your preference is remembered across sessions.

***

## Available Commands

All commands accept a leading `/` (e.g., `/help`, `/list`). The slash also triggers the autocomplete dropdown — see [Command Autocomplete](#command-autocomplete) below.

| Command                                     | Description                                                             |
| ------------------------------------------- | ----------------------------------------------------------------------- |
| `/help [command]`                           | List all commands, or describe a specific one                           |
| `/list` (alias: `/workflows`)               | Display available workflows                                             |
| `/<workflowId>`                             | Start a workflow interactively                                          |
| `/<workflowId> --from <stage> --to <stage>` | Run a specific stage range                                              |
| `/status [runId]`                           | Show the current state of a run, or the active run if no ID is provided |
| `/cancel [runId]`                           | Cancel a running workflow, or the active run if no ID is provided       |
| `/clear`                                    | Clear the terminal output                                               |

### Command Autocomplete

Type `/` at the prompt to open the suggestions dropdown. It surfaces every built-in command plus every workflow registered in your sandbox.

* **↑ / ↓** — Move through suggestions
* **Tab** — Insert the highlighted suggestion
* **Enter** — Run the highlighted suggestion
* **Esc** — Dismiss the dropdown

The list filters live as you keep typing — e.g., `/f` narrows to commands starting with `f` such as `/fulfill-order`.

***

## Available Workflows

Run `/list` in the terminal to see all workflows available in your sandbox:

```
$ /list
Found 3 workflow(s):
[1] /receive-wro       — 5 stage(s), 1 input field(s)
[2] /fulfill-order     — 5 stage(s), 1 input field(s)
[3] /adjust-inventory  — 2 stage(s), 1 input field(s)
```

| Workflow            | Stages | Description                                                 |
| ------------------- | ------ | ----------------------------------------------------------- |
| `/receive-wro`      | 5      | Simulates a warehouse receiving order (WRO) being processed |
| `/fulfill-order`    | 5      | Simulates the complete fulfillment lifecycle for a shipment |
| `/adjust-inventory` | 2      | Simulates an inventory quantity adjustment                  |

***

## Tutorial: Simulating Order Fulfillment

The `/fulfill-order` workflow is the most commonly used simulation. It walks a shipment through every stage of the fulfillment pipeline — from picking to delivery — so you can test webhook handlers, polling logic, and UI state transitions without touching real inventory.

### Step 1: Get a Shipment ID

From the **Orders** page in your sandbox, find a shipment in `Awaiting Pick` status and copy its Shipment ID (e.g., `106675083`).

### Step 2: Start the workflow

In the Simulation Terminal, type:

```
$ /fulfill-order
```

When prompted, enter the Shipment ID:

```
Workflow: Fulfill Order — Complete order fulfillment lifecycle
Enter Shipment ID: 106675083
```

### Step 3: Choose stages to run

The workflow will display all available stages:

```
Available stages:
  1. Picked     — Start pick, fetch pick lines, and perform picks
  2. Packed     — Complete packing
  3. Shipped    — Generate label, print, and validate
  4. InTransit  — Update tracking status to InTransit
  5. Delivered  — Update tracking status to Delivered

Enter start stage number (1-5), or press Enter to run all:
```

* Press **Enter** to run the full workflow from start to finish.
* To run a specific stage range, use the `--from` and `--to` flags instead:

```
$ /fulfill-order --from 2 --to 4
```

### Step 4: Watch real-time progress

The terminal streams live progress as the workflow runs:

```
[ 0%] Fulfill Order - Starting...
[ 0%] Fulfill Order - Picked
  → Fetch Shipment Details          ✓ (0.08s)
  → Start Shipment Pick             ✓ (4.89s)
  → Get Shipment Pick               ✓ (1.10s)
  → Pick Lines                      ✓ (2.53s)
✓ Picked (8.61s)

[25%] Fulfill Order - Packed
  → Fetch Shipment Details          ✓ (0.09s)
  → Complete Packing                ✓ (0.55s)
✓ Packed (2.95s)

[38%] Fulfill Order - Shipped
  → Fetch Shipment Details          ✓ (0.04s)
  → Generate Label                  ✓ (9.49s)
  → Print Label                     ✓ (0.12s)
  → Label Validated                 ✓ (0.09s)
✓ Shipped (9.74s)

[63%] Fulfill Order - InTransit
  → Fetch Shipment Details          ✓ (0.09s)
  → Get Shipment Tracking Info      ✓ (0.08s)
  → Update InTransit Status         ✓ (0.22s)
✓ InTransit (0.39s)

[81%] Fulfill Order - Delivered
  → Fetch Shipment Details          ✓ (0.03s)
  → Get Shipment Tracking Info      ✓ (0.04s)
  → Update Delivered Status         ✓ (0.07s)
✓ Delivered (0.16s)

[100%] Fulfill Order - Complete
✓ Workflow completed (32.4s)
```

Each stage maps to real status transitions in the ShipBob platform. You can use these to verify that your integration correctly handles each shipment status.

Pro tip: click the refresh icon after running a simulation to see the shipment update.

### Shipment Status Transitions

| Stage     | Resulting Shipment Status |
| --------- | ------------------------- |
| Picked    | `Picked`                  |
| Packed    | `Packed`                  |
| Shipped   | `Labelled` → `Shipped`    |
| InTransit | `InTransit`               |
| Delivered | `Delivered`               |

***

## Other Workflows

### `/receive-wro`

Simulates a Warehouse Receiving Order being processed at a ShipBob fulfillment center. Useful for testing inventory replenishment flows and WRO webhook events.

```
$ /receive-wro
Workflow: Receive WRO — Simulate warehouse receiving lifecycle
Enter WRO ID: <your-wro-id>
```

### `/adjust-inventory`

Simulates an inventory quantity adjustment. Useful for testing low-stock alerts, inventory sync logic, or backorder scenarios.

```
$ /adjust-inventory
Workflow: Adjust Inventory — Simulate inventory level change
Enter Inventory ID: <your-inventory-id>
```

***

## Tips

* **Refresh after a simulation** — The current page doesn't auto-update. Click the refresh icon in the table or open a new tab to see the latest shipment or inventory state.
  ![Simulation Terminal on the Orders page](https://files.buildwithfern.com/ship-dev.docs.buildwithfern.com/245e6f11c79abee5662a2a3ddbd73cc7811480cdd2602ff00ca999cea779b47f/docs/assets/images/simulations-3.png)

* **Run partial workflows** — Start from any stage to test a specific status transition without re-running the full lifecycle.

* **Chain workflows** — Run `/receive-wro` to stock inventory, then `/fulfill-order` to move it through fulfillment, all in the same sandbox session.

* **Verify webhooks in real time** — The terminal's live output is synchronized with the actual API calls, so webhook events fire at the exact moment each stage completes.

* **Discover commands fast** — Press `/` at any time to open the autocomplete dropdown, then `Tab` or `Enter` to insert the highlighted command. Workflow IDs appear in the same list once your sandbox finishes loading them.

* **Switch themes** — Use the sun/moon icon in the panel header to toggle between dark and light mode. Dark mode is the default; your choice is persisted per browser.

***

## Supported Environments

The Simulation Terminal is available exclusively in **sandbox** accounts (`webstage.shipbob.dev`). It is not available in production.

***

## FAQ

**Using the UI Terminal**, the following workflows are supported:

* **Fulfill Order** — Simulate shipping and delivering an order (5 stages).
* **Receive WRO** — Simulate receiving a warehouse receiving order (5 stages).
* **Adjust Inventory** — Simulate inventory adjustments (2 stages).

**Using the API**, you can simulate shipment events only:

* **Mark as Shipped** — Mark a shipment/order as shipped.
* **Mark as Delivered** — Mark a shipment/order as delivered.

No. The order cannot be On-Hold, Exception, or Cancelled.

No. Simulations are only supported in the Sandbox.

Yes. Inventory must be available in a supported fulfillment center.