Returns
How to create and manage returns using the ShipBob API
A return in ShipBob refers to a request to process inventory being sent back to their fulfillment centers, typically for customer refunds or exchanges. ShipBob manages the physical handling of returned items, but refunds or exchanges are handled by your system.
The 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
Prerequisites
To get started, you’ll need:
- ShipBob Sandbox Account: Sign up at ShipBob’s sandbox signup page.
- Personal Access Token: Generate this in the ShipBob dashboard under Integrations > API Tokens. Alternatively, use OAuth2.
- Channel ID: Fetch this with a
GET
request tohttps://sandbox-api.shipbob.com/2.0/channel
using your token. Look for a channel starting with “Personal Access Token…” and note itsid
. - Inventory IDs: Identify the
inventory_id
values for items being returned.
Creating a Return
Use the Create Return Order endpoint to start a return:
- Endpoint:
POST https://sandbox-api.shipbob.com/2.0/return
(switch toapi.shipbob.com
for production) - Authentication: Add your Personal Access Token in the
Authorization
header or use OAuth2. - Header: Include
shipbob_channel_id
with your channel ID.
Request Body
The request body is a JSON object with these fields:
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
:- Each object represents one type of item.
- Use each
inventory_id
only once per return. - Optional
requested_action
values:Default
,Restock
,Quarantine
, orDispose
.
Example Request
- Notes:
reference_id
: Links to “TEST_RETURN_12345” in your system.inventory
: Two items returned in one box.tracking_number
: Speeds up processing at ShipBob.
Key Rules
- One Box, One Return: Each physical shipment needs its own return order.
- No Duplicates: Each
inventory_id
must appear only once in theinventory
array. - Physical Items Only: Exclude digital items or bundles.
Handling Responses
Success Response
A 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”).
Error Responses
- 400 Bad Request: Invalid data (e.g., duplicate
inventory_id
). - 401 Unauthorized: Missing or invalid authentication.
Best Practices
Unique reference_id
: Make it immutable and traceable in your system.Add tracking_number
: Optional but accelerates processing.- One Return per Box: Match returns to physical shipments.
- Choose Actions Carefully: Set
requested_action
based on merchant needs. - Test in Sandbox: Use a Shopify dev store to sync products and orders.
Monitoring Returns
Track returns with the Get Return Orders endpoint:
- Endpoint:
GET https://sandbox-api.shipbob.com/2.0/return
- Parameters: Filter by
reference_id
,status
, orid
.
Statuses
- Awaiting Arrival: Return is inbound; can be modified or canceled.
- Processed: Inspection underway; no changes allowed.
- Completed: Processing done; no further edits.
Quality Grading
requested_action
: Your requested outcome (e.g., “Restock”).action_taken
: ShipBob’s final action post-inspection (e.g., “Dispose” if defective).
Diagrams
Creating a Return
Returns FAQs
How to find the return address?
How to find the return address?
Make a request to the GET FulfillmentCenter endpoint to get the fulfillment centers the ShipBob user has access to and the address.
How to find the actions that can be taken on a return?
How to find the actions that can be taken on a return?
Here are the available options: Default
, Restock
, Quarantine
, Dispose
.
How to find inventory ID based on the Shopify variantID?
How to find inventory ID based on the Shopify variantID?
- Make request to GET Products endpoint and pass the Shopify variant ID as the reference ID:
/1.0/product?referenceids={shopify-variantId}
- In the product response, find the inventory ID in the
fulfillable_inventory_items
array