***
title: Returns
description: How to create and manage returns using the ShipBob API
last-updated: 'February 24, 2026'
---------------------------------
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 are handled by your system.
The **`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.
To get started, you’ll need:
1. **Personal Access Token:** Generate this in the ShipBob dashboard under **Integrations > API Tokens**. Alternatively, use OAuth2.
2. **Channel ID:** Fetch this with a `GET` request to [`/2026-01/channel`](https://developer.shipbob.com/api/channels/get-channels) using your token. Look for the channel that has `_write` scopes and note its `id`.
3. **Fulfillment Centers:** Fetch this with a `GET` request to [`/2026-01/fulfillment_center`](https://developer.shipbob.com/api/receiving/get-fulfillment-centers). Choose the fulfillment center you want to create the return and note its `id`.
4. **Inventory IDs:** Identify the inventory `id` values for items being returned.
***
## Creating a Return
Use the [**Create Return Order**](/api/returns/create-return-order) endpoint to start a return:
* **Endpoint**: `POST api.shipbob.com/2026-01/return` (use `sandbox-api.shipbob.com/2026-01/return` for sandbox)
* **Authentication**: Add your Personal Access Token in the `Authorization` header or use OAuth2.
* **Header**: Include `shipbob_channel_id` with your channel ID.
**Example Requests**
```json lines
{
"fulfillment_center": {
"id": 22
},
"inventory": [
{
"id": 9557855,
"quantity": 1,
"requested_action": "Default"
}
],
"tracking_number": "1Z9999W99999999999",
"original_shipment_id": "104458283",
"reference_id": "RETURN101"
}
```
If an item in your inventory is lot-tracked (meaning ShipBob tracks it by manufacturing/expiration date or by production batch), then every return for that item must include both: `lot_number` and `lot_date`. These two fields let ShipBob match the returned unit to the exact lot it originally came from.
```json lines highlight={10-11}
{
"fulfillment_center": {
"id": 22
},
"inventory": [
{
"id": 9557855,
"quantity": 1,
"requested_action": "Default",
"lot_number": "2222"
"lot_date": "2027-11-24T14:15:22Z"
}
],
"tracking_number": "2Z9999W99999999999",
"original_shipment_id": "104458283",
"reference_id": "RETURN101"
}
```
```json lines
{
"fulfillment_center": {
"id": 22
},
"inventory": [
{
"id": 9557855,
"quantity": 1,
"requested_action": "Default"
},
{
"id": 9557857,
"quantity": 2,
"requested_action": "Default"
}
],
"tracking_number": "3Z9999W99999999999",
"reference_id": "RETURN103"
}
```
**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
1. **Unique `reference_id`**: Make it immutable and traceable in your system.
2. **Add `tracking_number`**: Optional but accelerates processing.
3. **One Return per Box**: Match returns to physical shipments.
4. **Choose Actions Carefully**: Set `requested_action` based on merchant needs.
***
## Monitoring Returns
You have two ways to monitor the progress of a return:
1. **Webhook Notifications (Recommended)**
* Subscribe to **`return.updated`** or **`return.completed`** events.
* 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.
2. **Polling the Returns API**
* Use the **[Get Return Orders](/api/returns/get-return-orders)** endpoint to periodically check status:
* **Endpoint**: `GET /2026-01/return`
* **Parameters**: Filter by `reference_id`, `status`, or `id`.
* This is useful as a fallback if webhook delivery fails or isn’t set up.
***
## Diagram
```mermaid
sequenceDiagram
participant YourSystem as Your System
participant ShipBobAPI as ShipBob API
YourSystem->>ShipBobAPI: POST /return (Create Return)
ShipBobAPI-->>YourSystem: 201 Created (Status: AwaitingArrival)
ShipBobAPI->>ShipBobAPI: Return is processed
and completed
ShipBobAPI->>YourSystem: return.completed event (Status: Completed)
```
## Returns FAQs
You can subscribe to return webhooks in two ways:
1. **ShipBob dashboard (easiest):**\
Go to **Integrations → Webhooks → Add Subscription** in the ShipBob dashboard. Select the events you want: `return.created`, `return.updated`, and `return.completed`.
2. **API Setup:**\
Create a webhook subscription programmatically using the [Create Subscription API](/api/webhooks/create-subscription).
Make a request to the [GET FulfillmentCenter](/api/receiving/get-fulfillment-centers?explorer=true) endpoint to get the fulfillment centers the ShipBob user has access to and the address.
Here are the available options: `Default`, `Restock`, `Quarantine`, `Dispose` .
The return statuses are `AwaitingArrival`, `Arrived`, `Processing`, `Completed`, and `Cancelled`. See more [here](/status-reference).
* 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