Getting Started With ShipBob's Developer API
About this API
ShipBob is a technology-first fulfillment & storage provider for e-commerce merchants. With a distributed network of fulfillment centers across the US, we allow fast, affordable shipping to thousands of customers. Read more about us here.
There are two methods of using this API: a "Privileged Access Token (PAT)" for single-merchant or custom integrations, and an OAuth 2.0 process for general-purpose integrations or those that will be listed on ShipBob's App Marketplace. Please see the Auth tab for more details.
Terminology & Concepts
- A channel is a specific installation of an application built by a vendor on top of our API – e.g. “Kevin’s Shopify Store #133432” would be 1 channel
- A multi-channel application can read data from all channels that belong to the merchant but can only write data on behalf of its own channel - e.g. multi-channel "app #555" can read data from "Kevin's Shopify Store #133432" but can only write data on behalf of "app #555".
- A referenceId is a required field when creating a record using one of Shipbobs Post endpoints - e.g. when creating a product via the Post products endpoint, a product referenceId is required. The referenceId was created to allow developers to tieback records in ShipBob to their own upstream systems. ReferenceIds must be unique by channel.
- An order is an object that comes from an external source and is intended for ShipBob to fulfill.
- A shipment is an object that is the result of fulfillment of an order. An order can contain one or more shipments.
- A product (or channel product) is a virtual record created in ShipBob’s system via a channel. In order to fulfill orders, product records MUST be created in ShipBob’s system. Upon creating a product, ShipBob will automatically 1 matching inventory item for that product. Via our UI, users can then add more inventory items to point to that product in order to create bundles
- An inventory item is a representation of a physical good, that may or may not have physical stock in ShipBob’s fulfillment center. An inventory item can be related to multiple products (e.g. a merge, where multiple product records come from various channel sources but are actually the same physical good).
- A bundle 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: this can currently only be done from the ShipBob UI
- A merge is a situation where multiple products (that may be from different channels) resolve to one inventory item. This is most common when merchants use ShipBob to fulfill orders from multiple platforms (e.g. Shopify and Amazon). When an order containing any of these products is sent to ShipBob, a shipment containing that inventory item will be sent out. Note: this can currently only be done from the ShipBob UI
- A warehouse receiving order (WRO) is an order to receive inventory into ShipBob’s fulfillment center. Some other solutions call this an “ASN” or Advanced Ship Notice. WROs may contain or multiple inventory items with specific quantities.
- A return is an order to unpack returned inventory and restock, dispose, or quarantine it in ShipBob’s fulfillment center. This is the same thing as an "RMA". Returns can be optionally related to the original outbound shipment.
Access & Sandbox
Before you are able to interact with ShipBob's API, you must have an account. Accounts are free until physical inventory arrives, and the trial period does not expire.
We now have a Sandbox environment that can be used for testing - please sign up for an account, then request sandbox credentials using the same form. Note: click the "clear demo data" step on the onboarding page before sending test orders.
Once you have an account, request API credentials using this form.
FAQ and Support
Please review our documentation thoroughly. Common issues that come up are listed here:
Q: Why can't I see my products in the ShipBob UI?
A: We are undergoing a schema migration to better support new features. Thus, the API has concepts - like "product" - which are not yet reflected in the UI. What you see on the UI is an inventory item, which is automatically created when you send us a channel product.
Q: Why can't I submit an order for a product that already exists in ShipBob's UI?
A: At ShipBob you must create “channel product” records in our system in order to create orders. This is so we always have a unique and immutable tie to the upstream system, which reduces the risk of line item errors and order duplication. You cannot create orders with inventory_ids or with products created from other sources. Please review our documentation:
There are 2 ways to create products for your convenience:
- Create the products via the Product POST. If you pass through a SKU that already exists in the ShipBob UI as the product’s “reference_id”, we will automatically merge that product to the existing inventory. Otherwise, the merchant will have to manually “merge” the items using our UI
- Create the products using reference_id in the line item field for the Order POST. We will auto-create any unrecognized products when you send us orders. This replaces the products sync step described above. Similarly, we will auto-merge the items in the manner described above if appropriate.
If you have any questions, please email us at [email protected]. This will create a ticket with a 1-business day first response time.
API calls will be rate-limited to 150 requests per-minute using a sliding window, and will be totalled per user, per application across calls to any of the Shipbob APIs.