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.

​
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

{
  "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