Sandbox Simulations

Description

Our Sandbox simulations allow merchants to test their integrations before they start shipping with us. With these simulations, you can generate production-like data for specific actions and different states of those actions so that you can perform extensive testing and set up trigger alerts or any other actions beforehand.

What is Simulation APIs?

These are APIs that can help you generate specific actions which are performed inside our ShipBob facility, where you can generate requests with data and get realistic responses that will happen in our facility. It is a fast and easy way of testing the integration even before it goes live. Thus, Simulation APIs let you identify any scenarios where your API can fail and allow you to better utilize these APIs by fixing those issues.

How to get started with Simulation APIs?

  1. Sign up for our SandBox environment, here.

    • Note: Your data from the production environment will NOT be copied over; it is a clean environment.
  2. Generate your API access token, using this form.
  3. Remove Demo Data from your account.

    • Login to the SandBox Merchant App -> Your Account - > Click on “Go Live”
  4. Point all your API calls to the below base URLs for each endpoint:

How does a Simulation function?

  1. Send a request using any of our Simulation APIs
  2. In response, it will generate a simulation ID

Note: Once the request is made, the simulation would run asynchronously in the background, as it may take some time to execute.

What actions can be simulated?

Multiple actions can be simulated, although only a couple can be simulated in SandBox as of now.

  • Available for self-service in Sandbox environment

    • Marking a Shipment/Order as Shipped
    • Marking a Shipment/Order as Delivered
  • Available on request (Manually), by sending an email to [email protected]

    • Adding or Modifying on-hand Inventory
    • Marking a WRO as Arrived or Completed
    • Creating a Return for a product
    • Adding a Serial number to a Shipment/Order
    • Splitting an order into multiple Shipments

Note: Please mention the email address of the parent account which is used to create the ShipBob account in the SandBox environment.

Shipment Simulation

Below are the actions the merchant can perform using simulation APIs in the SandBox Environment:

  1. Marking a Shipment/Order as Shipped
  2. Marking a Shipment/Order as Delivered

Prerequisites

Below are the steps that need to be completed before you start executing any Simulation API

  1. The shipment should contain products with inventory

    • To set up inventory, please send an email to [email protected]
    • Shipment products should have inventory available in the below Fulfillment Centers.

      • Cicero (IL)
      • Moreno Valley (CA)
  2. Packing preferences should be set for the product

    • Setup packaging preferences: Login to the Merchant App Dashboard -> Products -> Select the product -> Packaging Preferences
  3. The product should contain Custom Information if the shipment is for an International location

    • Setup the products you are going to use in shipment in the merchant app dashboard -> Products -> Select the product -> Customs Information
  4. If you would like to select the fulfillment center upon order creation, ensure it is one where inventory exists currently

    • Fulfilment Centers are allocated to a shipment during order creation, learn more here
    • If you want to test the simulation for a shipment with another Fulfilment Center allocated, please email [email protected] or refer to this help center article to change the shipment Fulfilment Center.
  5. Shipment shouldn't be in On-Hold, Exception/Canceled status.
  6. Adding a Dummy Payment method: Following the steps below:

    • Login to the ShipBob Merchant App dashboard
    • Go to Your Account-> Payment Details section
    • Add Dummy credit card details

      • Enter Card Number: 4111 1111 1111 1111, find some more here
      • Enter any Name, Email, CVC, and Expiration date

Note: Test data for orders created for simulation should have different products/items or the same items with different inventories.

Structure of Simulation APIs

Below is the breakdown of the structure of the Simulation API’s

ENDPOINT URL: POST 2.0/simulate/shipment

AUTHORIZATIONS: oauth2 (orders_read, orders_write)

HEADER PARAMETERS:

Name Description
shipbob_channel_id
required
integer (int32)
Channel Id for Operation

REQUEST BODY SCHEMA:

application/json-patch+json
Name Description
shipment_id
required
string
Shipment Id for simulation
simulation
required
Object
Simulation actions in tags
action
required
string
Enum: "ShipOrder" "DeliverOrder"
Identifies what action to perform on shipment.
delay string nullable
delay time for action in minutes to be triggered after
[min: 1, max:2880]
next Object nullable
next simulation action to be performed after it

Responses

200 Success

RESPONSE SCHEMA: application/json

Name Description
simulation_id UUID
Simulation id for register simulation request
message string
Simulation registered successfully
400 Bad Request

RESPONSE SCHEMA: application/json

Name Description
error_id UUID
Error id (can be shared with ShipBob support team in case of unexpected errors)
error string
Message for the error occurred in simulation request
404 Not Found

RESPONSE SCHEMA: application/json

Name Description
error_id UUID
Error id (can be shared with ShipBob support team in case of unexpected errors)
error string
"Could not find a shipment for the shipment id.”
500 Internal Server Error

RESPONSE SCHEMA: application/json

Name Description
error_id UUID
Error id (can be shared with ShipBob support team in case of unexpected errors)
error string
“Failed to register simulation. If you believe this is unexpected, please contact us at [email protected] with the provided error id”
401 Unauthorized

“No access right at this time”

403 Forbidden Access

“No access”

Below are some sample requests for different simulation actions

  1. Marking an Order/Shipment as Shipped

    {
        "shipment_id" : 11471145,
        "simulation" : {
            "action" : "ShipOrder",
            "delay" : null,
            "next" : null
        }
    }
    
  2. Marking an Order/Shipment as Delivered

    {
        "shipment_id" : 11471145,
        "simulation" : {
            "action" : "DeliverOrder",
            "delay" : null,
            "next" : null
        }
    }
    
  3. Marking a Order/Shipment as Shipped and Delivered in a single request

    {
        "shipment_id" : 11471145,
        "simulation" : {
            "action" : "ShipOrder",
            "delay" : null,
            "next" : {
                "action" : "DeliverOrder",
                "delay" : null
            }
        }
    }
    
  4. Marking a Order/Shipment as Shipped and Delivered in a single request with Delay

    {
        "shipment_id": 11471145,
        "simulation": {
            "action": "ShipOrder",
            "delay": 5,
            "next": {
                "action": "DeliverOrder",
                "delay": 10
            }
        }
    }
    



FAQ ?

  • What all statuses can I simulate for an order?

    • Marking an order as Shipped
    • Marking an order as Delivered
  • Can I simulate an order in any state?

    • No, orders which are in ‘On-Hold’/’Exception/Cancelled’ status can’t be simulated.
  • Can I simulate multiple actions?

    • Yes, you can simulate multiple actions in one request.
  • Can I simulate a production environment?

    • No, the simulation will work on our SandBox Environment.
  • Can I simulate the Shipped/Delivered status if I do not have inventory?

    • No, you need to add inventory before running the simulation.
  • What is the maximum level of nesting of Actions for a simulation?

    • Maximum 5 nested actions, nesting of more actions will be skipped.
  • What happens if I pass a delay of more than 2 days (2880 minutes)?

    • System will set a delay of 2880 minutes, so your request will be automatically processed after 2880 minutes.