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 are 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?

NOTE: Your data from the production environment will NOT be copied over; it is a clean environment.

Generate your API access token. Choose which type of token you want to use.
- Personal Access Token (PAT): Single-user: A custom integration for 1 merchant using ShipBob. Generate this from the Sandbox ShipBob dashboard. For detailed steps, click here.
- OAuth: General purpose: An application or integration that multiple merchants can use to connect to ShipBob. For example: a connector with Shopify. Send us the details using this form.

NOTE: For detailed info about these tokens, click here.

Remove Demo Data from your account.
- Login to the SandBox Merchant App -> Your Account - > Click on “Go Live”.
Point all your API calls to the below base URLs for each endpoint:
- For Sandbox API: https://sandbox-api.shipbob.com/2.0/
- For Sandbox Auth: https://authstage.shipbob.com/

How does a Simulation function?

Send a request using any of our Simulation APIs.
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.*

Rate Limits

ShipBob API calls will be limited to 150 requests per minute, using a sliding window and totaled per user, per application.

Shipment Simulation

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

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

Prerequisites

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

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)
Packing preferences should be set for the product.
- Setup packaging preferences: Login to the Merchant App Dashboard -> Products -> Select the product -> Packaging Preferences.
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.
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.
Shipment shouldn't be in On-Hold, Exception/Canceled status.
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	`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 Simulation actions object.

Simulation Object

Name	Description
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` Simulation 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 that occurred in the 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”

Simulation Status API

ENDPOINT URL	GET 2.0/simulate/status/{simulation_id}
AUTHORIZATIONS	oauth2

Responses

200 Success

RESPONSE SCHEMA: application/json

Name	Description
simulation_id	`string` Simulation id for register simulation request.
entity_id	`string` ID of the entity for which the simulation was registered.
entity_type	`string` Type of entity for which the simulation was registered.
simulation	`Object` SimulationDetails Object with details of simulation actions

Simulation Details Object

Name	Description
action	`string` Enum: "ShipOrder" "DeliverOrder" Identifies the action that was performed.
status	`string` Enum: "Success" "Failed" "Pending" "Skipped" Status of the simulation action..
message	`string` Enum: "ShipOrder" "DeliverOrder" Additional message for the action.
schedule_time	`datetime` nullable Scheduled time if the action had a delay.
next	`Object` SimulationDetails nullable Nested object with details of subsequent simulation actions. This value would be null if there is no subsequent action.

400 Bad Request

RESPONSE SCHEMA: application/json

Name	Description
message	`string` If provided simulation_id is incorrect.

404 Not Found

RESPONSE SCHEMA: application/json

Name	Description
message	`string` If provided simulation_id does not exist.

401 Unauthorized

“No access right at this time”

403 Forbidden Access

“No access”

Below are some sample requests for different simulation actions

Marking an Order/Shipment as Shipped

{
    "shipment_id" : 11471145,
    "simulation" : {
        "action" : "ShipOrder",
        "delay" : null,
        "next" : null
    }
}

Marking an Order/Shipment as Delivered

{
    "shipment_id" : 11471145,
    "simulation" : {
        "action" : "DeliverOrder",
        "delay" : null,
        "next" : null
    }
}

Marking an Order/Shipment as Shipped and Delivered in a single request

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

Marking an 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.