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

In the Sandbox, you can currently simulate these self-service actions:

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

Want to test other actions (like adding inventory or creating returns)? Email [email protected] with your request and the email tied to your Sandbox account.


Step 4: Prepare Your Shipment for Simulation

Before you run a simulation, make sure your shipment is ready. Here’s what you need:

  • Inventory: The shipment’s products must have inventory in one of these fulfillment centers:
  • Packaging Preferences: Set these up in the Merchant App Dashboard under Products > [Your Product] > Packaging Preferences.
  • Customs Info (for International Shipments): Add this in the Merchant App Dashboard under Products > [Your Product] > Customs Information.
  • Fulfillment Center: Ensure inventory exists in the chosen center.
  • Shipment Status: It can’t be On-Hold, Exception, or Canceled.
  • Dummy Payment Method: Add a test credit card:
    • Log in to the Merchant App Dashboard > Your Account > Payment Details.
    • Use card number 4111 1111 1111 1111, plus any name, email, CVC, and expiration date.

Step 5: Run a Simulation

Here’s how to send a simulation request:

Example Requests

Mark an Order as Shipped

POST https://sandbox-api.shipbob.com/2.0/simulate/shipment
{
    "shipment_id": 11471145,
    "simulation": {
        "action": "ShipOrder",
        "delay": null,
        "next": null
    }
}

Mark an Order as Delivered

POST https://sandbox-api.shipbob.com/2.0/simulate/shipment
{
    "shipment_id": 11471145,
    "simulation": {
        "action": "ShipOrder",
        "delay": null,
        "next": null
    }
}

Mark as Shipped, Then Delivered

POST https://sandbox-api.shipbob.com/2.0/simulate/shipment
 {
     "shipment_id": 11471145,
     "simulation": {
         "action": "ShipOrder",
         "delay": null,
         "next": {
             "action": "DeliverOrder",
             "delay": null
         }
     }
 }

Add Delays (e.g., Ship in 5 minutes, Deliver in 10 minutes)

POST https://sandbox-api.shipbob.com/2.0/simulate/shipment
 {
     "shipment_id": 11471145,
     "simulation": {
         "action": "ShipOrder",
         "delay": 5,
         "next": {
             "action": "DeliverOrder",
             "delay": 10
         }
     }
 }

What You’ll Get Back

  • Success (200): A simulation_id and a “Simulation registered successfully” message.
  • Errors: Check for 400 (bad request), 404 (shipment not found), or 500 (server issue—contact [email protected] with the error_id).

FAQ