​
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.

​
Step 1: Set Up Your Sandbox Environment

Before running simulations, make sure your sandbox account is ready. Follow our Sandbox Setup guide 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 developers@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

POST /2.0/simulate/shipment

Authorization: OAuth2 (orders_read, orders_write)
Header: shipbob_channel_id (integer)

​
Request Body Schema

{
  "shipment_id": 11471145,
  "simulation": {
    "action": "ShipOrder",
    "delay": null,
    "next": {
      "action": "DeliverOrder",
      "delay": 10
    }
  }
}
FieldDescription
shipment_idRequired. The ID of the shipment to simulate.
actionRequired. "ShipOrder" or "DeliverOrder".
delayOptional. Time in minutes (1–2880) to wait before running the action.
nextOptional. A nested object for the next simulation action (up to 5 levels).

​
Example Requests

Mark as Shipped:

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

Mark as Delivered:

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

Ship then Deliver with Delay:

{
  "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

GET /2.0/simulate/status/{simulation_id}

Authorization: OAuth2

​
Response (200 OK)

{
  "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"
    }
  }
}
FieldDescription
statusOne of Success, Failed, Pending, or Skipped.
schedule_timeTime the action is scheduled for (if delay was set).
nextNested action status (if multiple actions were simulated).

​
Simulation API Reference

EndpointMethodDescription
/2.0/simulate/shipmentPOSTRegister a simulation for a shipment.
/2.0/simulate/status/{id}GETGet the status of a simulation.

​
FAQ