reference_id 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:
- Personal Access Token: Generate this in the ShipBob dashboard under Integrations > API Tokens. Alternatively, use OAuth2.
- Channel ID: Fetch this with a
GETrequest to/2025-07/channelusing your token. Look for the channel that has_writescopes and note itsid. - Fulfillment Centers: Fetch this with a
GETrequest to/2025-07/fulfillment_center. Choose the fulfillment center you want to create the return and note itsid. - Inventory IDs: Identify the inventory
idvalues for items being returned.
Creating a Return
Use the Create Return Order endpoint to start a return:- Endpoint:
POST api.shipbob.com/2025-07/return(usesandbox-api.shipbob.com/2025-07/returnfor sandbox) - Authentication: Add your Personal Access Token in the
Authorizationheader or use OAuth2. - Header: Include
shipbob_channel_idwith your channel ID.
Example Requests
- Create Return
- Create Return with lot items
- Create Return with multiple items
Key Rules
- One Box, One Return: Each physical shipment needs its own return order.
- No Duplicates: The id (
9557855) appears only once. If you had multiple different physical items in the box, each would get its own unique entry here—but never repeated. - Physical Items Only: Exclude digital items or bundles.
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_actionbased on merchant needs.
Monitoring Returns
You have two ways to monitor the progress of a return:-
Webhook Notifications (Recommended)
- Subscribe to
return.updatedorreturn.completedevents. - ShipBob will send a webhook event to your system when a return’s status changes (updated) or when it is fully completed.
- This eliminates the need for continuous polling and ensures near real-time updates.
- Subscribe to
-
Polling the Returns API
- Use the Get Return Orders endpoint to periodically check status:
- Endpoint:
GET /2025-07/return - Parameters: Filter by
reference_id,status, orid.
- Endpoint:
- This is useful as a fallback if webhook delivery fails or isn’t set up.
- Use the Get Return Orders endpoint to periodically check status:
Diagram
Returns FAQs
How to subscribe to return webhooks?
How to subscribe to return webhooks?
You can subscribe to return webhooks in two ways:
-
ShipBob dashboard (easiest):
Go to Integrations → Webhooks → Add Subscription in the ShipBob dashboard. Select the events you want:return.created,return.updated, andreturn.completed. -
API Setup:
Create a webhook subscription programmatically using the Create Subscription API.
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 all the return statuses?
How to find all the return statuses?
The return statuses are
AwaitingArrival, Arrived, Processing, Completed, and Cancelled. See more here.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_itemsarray
