How to create and manage returns using the ShipBob API
referenceId
field is key—it’s a unique identifier from your system that links the return in ShipBob to your records, ensuring easy tracking and reconciliation.
Prerequisites
GET
request to https://sandbox-api.shipbob.com/2.0/channel
using your token. Look for a channel starting with “Personal Access Token…” and note its id
.inventory_id
values for items being returned.POST https://sandbox-api.shipbob.com/2.0/return
(switch to api.shipbob.com
for production)Authorization
header or use OAuth2.shipbob_channel_id
with your channel ID.Field | Type | Required? | Description |
---|---|---|---|
reference_id | String | Yes | Your system’s unique identifier (e.g., “RETURN_12345”) to track the return. |
inventory | Array | Yes | List of items being returned, each with an inventory_id and optional requested_action . |
tracking_number | String | No | Carrier tracking number for the return shipment—helps ShipBob identify it faster. |
inventory Details
:
inventory_id
only once per return.requested_action
values: Default
, Restock
, Quarantine
, or Dispose
.reference_id
: Links to “TEST_RETURN_12345” in your system.inventory
: Two items returned in one box.tracking_number
: Speeds up processing at ShipBob.inventory_id
must appear only once in the inventory
array.201 Created
status indicates success:
id
: ShipBob’s internal return ID.status
: Starts as “Awaiting Arrival.”action_taken
: Filled after inspection (e.g., “Restock” or “Dispose”).inventory_id
).Unique reference_id
: Make it immutable and traceable in your system.Add tracking_number
: Optional but accelerates processing.requested_action
based on merchant needs.GET https://sandbox-api.shipbob.com/2.0/return
reference_id
, status
, or id
.requested_action
: Your requested outcome (e.g., “Restock”).action_taken
: ShipBob’s final action post-inspection (e.g., “Dispose” if defective).How to find the return address?
How to find the actions that can be taken on a return?
Default
, Restock
, Quarantine
, Dispose
.How to find inventory ID based on the Shopify variantID?
/1.0/product?referenceids={shopify-variantId}
fulfillable_inventory_items
array