Guides

• Order POST – This allows you to create orders in ShipBob. Example API request is found in the documentation linked.
• Order GET – This allows you to fetch tracking details from ShipBob if you want to take a polling/scheduled based approach.
  • You can also subscribe to our webhooks if you’d like to automatically receive shipment events here.
• Inventory GET – This allows you to fetch inventory levels across ShipBob’s facility network. This endpoint will return per-facility inventory levels as well as aggregated inventory levels across the network.
  • The following inventory quantity calculations are available:
    • On hand quantities are everything currently stocked at the warehouse.
    • Fulfillable quantities are everything stocked at the warehouse minus quantities committed to orders.
    • Sellable quantities are everything stocked at the warehouse, minus quantities committed to orders, minus any exception orders. This calculation is only available at a network-wide level.
• Authentication is handled either via OAuth or a token-based approach. For a custom integration, we typically see the token approach used – you are able to generate an API token directly in your ShipBob dashboard. Steps here.

​

Create Orders

• Shipping method: This is typically a value such as “Standard”, “Expedited”, “2-Day”, etc. Once a ship method comes through via the integration, the merchant will have the ability to map the method to a specific Ship Option that will determine the shipment’s SLA and carrier selection. More detail on Ship Options can be found in our help center here.
• Recipient name - The name of the individual the shipment will be delivered to.
• Recipient address – specifically the Address1, City, and Country (ISO Alpha-2 code is highly recommended).
  • If available, please also pass the City and Zip Code.
• Reference id – This is a unique order number from the upstream platform being integrated with ShipBob. This number must be unique within ShipBob account.
  • You can also pass an optional order_number field. This does not need to be unique, and is a more user-friendly order number that a customer service agent might be more familiar with.
• Products – There are two methods for providing product data with your order payload to ShipBob:
  • ReferenceId Model (highly recommended) – This model allows you to pass a product’s reference_id (typically the SKU value), as well as the product name. When an order is created, ShipBob will check if the product already exists based on a matching reference_id, and will automatically create a new product if one does not already exist.
    • This model is recommended as you do not need to store any external ShipBob product id values to create an order successfully. It also has the ability to auto-create products if they do not exist based on the duplicate match of a reference_id value.
  • ProductId Model – This model requires that you pass ShipBob’s ProductId as part of the order payload to create the order. This will mean that you first must create a product using ShipBob’s Product API and have a method to either store or reference the ShipBob-generated ProductId to use as part of your order creation process.
    • This model works best if you always create products in ShipBob prior to sending any orders, and have a way to store the ProductId somewhere upstream.
  • When viewing the API documentation, you can toggle between each model by expanding the Product node:

"tags": [{
  "name": "AddMarketingInsert",
  "value": "NotUsedForRuleTrigger"
}],

​

Create B2B orders

• Ensure that the “type” is set to a value of 2 or “b2b” (this denotes a B2B order type).
• carrier_type will be either “Parcel” or “Freight” – recommended that you have the ability to select which of these options should be used.
• shipping_method should be “B2B”.
• payment_terms can either be “Prepaid” or “MerchantResponsible”.
  • This depends if you will be uploading your own labels on the ShipBob dashboard, or if ShipBob will provide the labels. If ShipBob will handle labels, then pass the value “Prepaid”.
• retailer_program_type should be set to “SB-B2B”.
• Pass a purchase_order_number.
• company_name within the recipient address data should be the retailer’s name.
• quantity_unit_of_measure_code should be “EA” for eaches

​

Creating channel products

• Reference_id (required) – this is typically the product SKU or it can be another unique identifier. ShipBob highly recommends to use a product’s SKU value for this field. When viewing a product in ShipBob’s UI, the reference_id API field translates the UI SKU value.
• Name (required) – this is the name of the product.
• Barcode (optional, recommended) – the product’s barcode. This is very useful to have available as it assists the receiving process when inbound inventory is sent to a ShipBob facility to be stowed.

​

Managing channel products

​

Bundle considerations

x1 Blue Shirt - SKU = 123123x1 Red Shirt - SKU = 234234x1 Hat - SKU = 345345

​

Option 1 – Deconstruct bundle prior to sending to ShipBob (preferred)

​

Option 2 – Construct bundle prior to sending to ShipBob

1. If a bundle SKU is sent in an Order POST to ShipBob, retrieving that order data will return the bundle SKU. The component SKUs will not be returned in an Order GET response, but the inventory ids of the component products will be returned.
2. Inventory quantities in ShipBob are tracked at the component level, not at the bundle level. You will need to conduct inventory level calculations for the bundle as a result.

​

Retrieving tracking and fulfillment details

​

Option 1 – Polling-based approach

• LastUpdateStartDate and LastUpdateEndDate – this allows you to implement a sliding time window so that you fetch only newly updates orders since the time you last checked ShipBob.
• HasTracking – this will filter orders only where tracking information has been made available (i.e. the order has shipped).

​

Option 2 – Webhooks

• Shipped event
• Delivery event
• Shipment exception event (such as a product being out of stock)
• Shipment On Hold event (such as an invalid address)
• Shipment cancelled event

• The Shipped topic will include a payload that is identical to the Order GET response detailed in method one above. In the event of a split shipment, you will receive multiple events when each individual shipment of an order has been shipped, which is when the shipment status has been updated to LabeledCreated.
• ShipBob uses an exponential backoff approach to deliver a webhook event to your endpoint for up to 24 hours. However, ShipBob cannot guarantee the delivery of retried events in the order in which they were originally generated. Therefore, if you have implemented a webhook solution that expects events to be delivered in a specific sequence, it is highly advised that you have a method in place to handle these events.

​

Retrieving inventory levels

​

Option 1 – Fetching products from ShipBob each time inventory levels are updated in your platform

1. Grab the products in bulk each time you are conducting an inventory sync (1 or multiple calls) using the Product endpoint
2. Get the list of the product’s inventory components (inventory_id is returned in the Product endpoint)
3. Grab all the inventories in bulk (1 or multiple calls) using the Inventory endpoint
4. Reconcile product with inventory. If not a bundle, grab the inventory id and set that as the product sellable. If it is a bundle, you need to do the calculations. If the inventory is inactive or digital, you can skip the product or place a 0 value.
   • Note - inventory quantities in ShipBob are tracked at the component level, not at the bundle SKU level.

​

Option 2 - Store products in your system

​

Creating warehouse receiving orders

​

Relevant ShipBob APIs:

• Warehouse Receiving Order POST
• Warehouse Receiving Order GET
• Box Labels GET
• Product POST
• Product GET

​

Details on WRO Creation

• The package_type field accepts the values of Pallet, Package, and FloorLoadedContainer
  • Pallet – if the inbound order is palletized, please include the Pallet tracking number and the contents of the pallet as a “box” within the ShipBob box array. If multiple pallets are being sent, please separate each pallet as its own “box” in the box array.
  • Package – please provide the package contents for each package/parcel being sent as part of that purchase order. Each package should have its own tracking number. Please note that a maximum of 50 “boxes” within the box array are allowed per WRO request.
  • Floor Loaded Container – please provide the entire contents of the container as one “box” within the box array and the container’s tracking number.
• The expected arrival date must be a date in the future, otherwise the WRO creation request will fail, and you will receive a 400 response with a description stating that the arrival date must be in the future.
• The ShipBob inventory_id (a unique ShipBob product identifier) is also a requirement for the WRO record to be created successfully. As a result, product records must first exist within the ShipBob WMS prior to the WRO request being sent to ShipBob. There are several strategies to accomplish this:
  • The recommended approach is for the integration to first check, via the Product GET API, if products within an inbound already exist within the WMS. If they do, the associated inventory_ids can be used in the WRO creation request. If they do not, they can be created via a Product POST request, and the request response will include the inventory_id.
  • The alternative approach is to store the ShipBob inventory_id upstream whenever a product is created via the integration.
• The purchase order number field should be populated with a unique PO number or shipment number.
• Provide the scannable carton ID in the tracking_number field for each box/pallet that the ShipBob operations team can physically scan when the WRO arrives at the warehouse.

​

Details on WRO Status Updates

• The “statuses” parameter can be used to fetch WROs that are in various statuses, such as Arrived, Processing, Completed.
  • When a WRO is first created, the status will default to “Awaiting”. Once the WRO has physically arrived at the warehouse and has been scanned by the Operations team, the status will update to “Arrived” or “PartiallyArrived”.
  • A Completed status means that all stowing has been completed and no further action will be taken against the WRO record.
  • A Processing status means that stowing is taking place; the “stowed_quantity” field within the “inventory_items” array will continually increase until stowing is complete for a product.
• The PurchaseOrderNumbers parameter can return specific WRO records associated with the purchase order numbers passed during the WRO creation.

​

​

Assumptions & Considerations

• WRO configuration updates are not supported via the ShipBob API. There is no API endpoint to update a WRO once it has been created.

​

Error Handling & Troubleshooting