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 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.
To get started, you’ll need:
  1. ShipBob Sandbox Account: Sign up at ShipBob’s sandbox signup page.
  2. Personal Access Token: Generate this in the ShipBob dashboard under Integrations > API Tokens. Alternatively, use OAuth2.
  3. Channel ID: Fetch this with a 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.
  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 https://sandbox-api.shipbob.com/2.0/return (switch to api.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:
FieldTypeRequired?Description
reference_idStringYesYour system’s unique identifier (e.g., “RETURN_12345”) to track the return.
inventoryArrayYesList of items being returned, each with an inventory_id and optional requested_action.
tracking_numberStringNoCarrier 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, or Dispose.

​
Example Request

  • Create Return
{
  "reference_id": "TEST_RETURN_12345",
  "inventory": [
    {
      "inventory_id": 12232,
      "requested_action": "Default"
    },
    {
      "inventory_id": 12039,
      "requested_action": "Default"
    }
  ],
  "tracking_number": "1Z9999W99999999999"
}
  • 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 the inventory array.
  • Physical Items Only: Exclude digital items or bundles.

​
Handling Responses

​
Success Response

A 201 Created status indicates success:
  • 201
{
  "id": 98765,
  "reference_id": "TEST_RETURN_12345",
  "status": "Awaiting Arrival",
  "inventory": [
    {
      "inventory_id": 12232,
      "requested_action": "Restock",
      "action_taken": null
    },
    {
      "inventory_id": 12039,
      "requested_action": "Dispose",
      "action_taken": null
    }
  ],
  "tracking_number": "1Z9999W99999999999",
  "created_date": "2025-10-15T10:00:00Z"
}
  • 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

  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.
  5. 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, or id.

​
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

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 .
  • 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