Use this to get started
ShipBob’s public API supports a variety of different use cases. This guide shows most common scenarios that you can create using ShipBob’s public APIs.
You can create a typical integration using the following endpoints:
ShipBob’s Order POST endpoint has several required fields that you need to be aware of:
In addition to the required fields highlighted above, you also have the ability to pass order tags to ShipBob. Tags are an array that consists of a name, value pair which can be used to store additional data that might be needed with your platform upstream, and can also trigger automation rules that have been created in ShipBob.
More details on available rules can be found here.
To trigger a rule created within ShipBob, the order tag name must match the rule. As an example, if you desire to pass a tag that triggers a rule to automatically add a marketing insert to specific orders, your tag structure may look like:
Where the tag “name” value of “AddMarketingInsert” is what will be used to trigger a rule created in ShipBob.
Lastly, you will need to also specific a shipbob_channel_id
within the request header to successfully create an order. To find which channel you have write access to, you can call the GET Channel endpoint to view a list of permissions you have access to under each channel. You will only have write access for one channel (your own integration channel), but you typically will have the ability to read data across other channels.
ShipBob has the ability to ingest generic B2B orders via the public API. Please note that these are B2B orders which do not have retailer compliance standards, ShipBob standard packing slips, boxes, GS1 labels will be used for these orders. If you are working with retailers that have compliance guidelines that ShipBob must adhere to, please reach out to your Merchant Success Manager for additional assistance.
Generic B2B orders passing through ShipBob’s API must be sent with specific required fields to ensure they fall under our B2B flow as opposed to the default D2C flow.
Attached, you will find an example API request for a general b2b order. While reviewing this example, there are several fields to note within this payload that differ from a standard D2C order:
A product in ShipBob is a fulfillable item that will exist on orders and shipments. To create a product via the ShipBob API, this can be handled either by creating a single product, or creating products in bulk. There are two required fields to successfully create a product in ShipBob, as well as a recommended optional field:
When creating a product under the channel that you have write access to, you are creating a channel product, or a digital representation of a physical good. A channel product will be associated with an inventory item, which is the physical representation of that good that holds inventory levels and other item attributes. Since a channel product is a digital representation, it is possible for that same item to exist across various different channels.
As an example, if your integration creates a channel product “SKU123”, the merchant could also be connected between ShipBob and other integrations, such as Shopify, BigCommerce, Magento, NetSuite, etc. Each of these integrations manages their own channel products, so “SKU123” could be a channel product for each of those integrations as well. Each channel product will resolve to the same inventory item, which is the item that is visible in the ShipBob UI. As a result, despite multiple channel products for the same item existing, you will only see the one inventory item when searching for “SKU123” in the ShipBob UI:
A bundle on ShipBob is a product that resolves to multiple inventory items. This is most commonly used for gift or multi packs. When an order is received for this product, the shipment will contain all the inventory items associated with the bundle. Note: The association of a product to bundle can currently only be done from the ShipBob UI.
Bundles are a way to associate multiple pre-defined SKUs with specific quantities within an order.
For example, an example merchant might have a bundle called Bundle A, which correlates to:
x1 Blue Shirt - SKU = 123123x1 Red Shirt - SKU = 234234x1 Hat - SKU = 345345
The bundle itself also has its own SKU, such as BUNDLE123.
There are two primary options for handling bundles via ShipBob API.
ShipBob ultimately needs all products at the variant/component level as this is what ShipBob fulfillment centers pack shipments with.
If the upstream system that is integrating with ShipBob is able to deconstruct bundles into the component SKUs prior to sending to ShipBob, ShipBob will also return the component SKUs within the fulfillment data, so the upstream system may need to also reconstruct bundles based on the capabilities of the system, how inventory is calculated, or other merchant requirements.
This option means that bundles would not need to be maintained in ShipBob directly, as ShipBob will only create products at the component level. This is more user friendly for the merchant as they will not need to manually convert a product to be a bundle, or create bundles via the ShipBob dashboard.
In ShipBob, bundles can be created directly in the UI from a product. A product can be marked as a Bundle, and then a merchant is able to breakdown the component SKUs that make up that bundle.
The ability to mark the product as a bundle is not available with an API request, so if bundles will be maintained within ShipBob directly, the merchant will need to manually update a product to be a bundle and ensure that all component SKUs are correctly associated with the bundle product. Here is a tutorial on managing bundles in ShipBob.
Once correctly configured in ShipBob, the integration would be able to send the specific bundle SKU, and ShipBob fulfillment centers will ship all products comprising that bundle.
Considerations with this option:
There are two primary options for retrieving shipment details from ShipBob.
This method allows you to fetch tracking details from ShipBob on demand using the GET Orders endpoint. There are several parameters to choose from depending on your use case, but the most common params used are:
You also can specify a shipbob_channel_id
header parameter. It is advised to pass this parameter for the channel you have write access to, so you only retrieve order and shipment details from orders that were created from your integration. Excluding the channel id will be a global search across all channels for the Merchant, which has the possibility to retrieve order details from other sources/integrations a merchant has installed that you may not need.
If your platform supports split orders/shipments, you will need to refer to the multiple shipment objects returned in the API response in the event that an order has been split.
Within the order response, you will see an array of shipments (please refer to the sample response in the documentation linked above). An order can have a one-to-many relationship to shipments if the order has been split. Each shipment associated with an order will have a unique tracking number and will detail which products have been packed and shipped as part of that individual shipment.
Each shipment will also have a status. When a shipment has tracking details, the shipment status will be “LabeledCreated”. This status will quickly move to “Completed”. If you have a use-case that requires you to look at specific ShipBob statuses, it is recommended to use both statuses when checking for tracking details from ShipBob.
To see more detail on other statuses you may encounter, please refer to our documentation here.
ShipBob has the ability to fire webhooks for certain shipment events. The topics that can be subscribed to are:
Each topic can be subscribed to individually via a webhook POST request. Request details can be found here. ShipBob also has several example payloads on the webhook page of our documentation here.
A couple critical pieces to note:
ShipBob’s GET inventory endpoint will return inventory quantities associated with products that are stocked at a facility. This endpoint will return an inventoryid associated with a product, which is a unique ShipBob identifier. When creating a product via ShipBob’s product API, an inventoryid is automatically generated and retuned in the product creation response. As such, ShipBob recommends implementing one of the following best practices to fetch inventory levels:
The solution would be to follow this process:
If overselling is a large issue, you can also implement a “buffer” for certain skus, meaning that if you want to stop sales upstream at, say, 20 remaining inventory for a sku, you can send a 0 quantity to your platform of the 20 or less that ShipBob is reporting for that particular sku. This buffer will allow for a certain “reserve” stock on the ShipBob end in case there any customer service/high priority orders that need to be pushed through and fulfilled. The buffer quantity logic would need to live on your platform/integration layer, and you can decide to do this on a per-sku basis or a global setting across all skus.
The alternative solution would be for you to store the ShipBob Inventory Id somewhere on your system. This way, you can use the bulk inventory endpoint and page through all inventory records that ShipBob returns to update your system’s inventory levels. The only caveat is that if a product merge happens on ShipBob, the inventoryid could change, so you’d need a way to reconcile the inventory ids on a regular basis to ensure you store the correct id.
This would also mean that when a product is created via the API, you have the ability to store the inventory id based on the product creation response.
ShipBob’s inbound receiving process comes in the form of Warehouse Receiving Orders (WROs). A WRO can be created via the ShipBob API.
The WRO POST request requires several fields to be populated based on how the inbound will be sent to ShipBob.
ShipBob’s GET Warehouse Receiving Order API will allow an on-demand fetch of WROs within a ShipBob account and the current status associated with each individual WRO.
Several parameters can be used to fetch WROs by status or by specific WRO record:
Depending on the use-case, the integration can continuously poll a WRO and monitor the “stowed_quantity” for each product as the stowing occurs during the WRO’s Processing status, or wait until the WRO is in Completed status before updating inventory in the upsteam platform.
Additionally, the GET WRO Boxes endpoint can be used to fetch the status for each box individually, which will also include the received quantities per box.
Common Errors & Solutions
Error Code | Meaning | Solution | |
---|---|---|---|
400 Bad Request | Missing required field | Ensure all required fields are included | |
401 Unauthorized | Invalid API token | Verify authentication headers | |
404 Not Found | Invalid endpoint or ID | Check endpoint and request parameters | |
429 Too Many Requests | Rate limit exceeded | Implement exponential backoff retries |