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.

​

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 [email protected].

​

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
    }
  }
}

​

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

​

Simulation API Reference

​

FAQ