Skip to main content
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 /2025-07/channel 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 /2025-07/fulfillment_center. 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 endpoint to start a return:
  • Endpoint: POST api.shipbob.com/2025-07/return (use sandbox-api.shipbob.com/2025-07/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

  • Create Return
  • Create Return with lot items
  • Create Return with multiple items
{
  "fulfillment_center": {
    "id": 22
  },
  "inventory": [
    {
      "id": 9557855,
      "quantity": 1,
      "requested_action": "Default"
    }
  ],
  "tracking_number": "1Z9999W99999999999",
  "original_shipment_id": "104458283",
  "reference_id": "RETURN101"
}

​
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 endpoint to periodically check status:
      • Endpoint: GET /2025-07/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

​
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.
Make a request to the GET FulfillmentCenter 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.
  • 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
⌘I