Skip to main content
POST
/
2025-07
/
return
Create a return. 
curl --request POST \
  --url https://api.shipbob.com/2025-07/return \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'shipbob_channel_id: <shipbob_channel_id>' \
  --data '
{
  "fulfillment_center": {
    "id": 0,
    "name": "string"
  },
  "inventory": [
    {
      "id": 0,
      "lot_date": "2019-08-24T14:15:22Z",
      "lot_number": "string",
      "quantity": 0,
      "requested_action": 0
    }
  ],
  "original_shipment_id": 0,
  "reference_id": "string",
  "tracking_number": "string"
}
'
{
  "channel": {
    "id": 0,
    "name": "string"
  },
  "completed_date": "2019-08-24T14:15:22Z",
  "customer_name": "string",
  "fulfillment_center": {
    "id": 0,
    "name": "string"
  },
  "id": 0,
  "insert_date": "2019-08-24T14:15:22Z",
  "inventory": [
    {
      "action_requested": {
        "action": "string",
        "action_type": "string",
        "instructions": "string"
      },
      "action_taken": [
        {
          "action": "string",
          "action_reason": "string",
          "image_url": "http://example.com",
          "quantity_processed": 0
        }
      ],
      "id": 0,
      "name": "string",
      "quantity": 0
    }
  ],
  "invoice_amount": 0.1,
  "original_shipment_id": 0,
  "reference_id": "string",
  "return_type": "string",
  "status": "string",
  "store_order_id": "string",
  "tracking_number": "string",
  "transactions": [
    {
      "amount": 0.1,
      "transaction_type": "string"
    }
  ]
}
Use the Returns resource to retrieve, create, edit, and cancel return records in ShipBob. A return is a request for ShipBob to perform an action on inventory that is coming back into our fulfillment centers. Typically, the return is a result of an order being requested to be refunded or exchanged. ShipBob does not handle refunds or exchanges – we simply process the inventory according to the merchant specifications.
Returns can only be modified or cancelled when they are in the AwaitingArrival status. Returns that are in the Processing or Completed status cannot be modified or cancelled.

​
Tips for Creating Return Orders

  • Populate the reference_id with a unique and immutable return identifier from your upstream system. This field was created to allow you to tie back records in ShipBob with your upstream system.
  • Include each inventory_id exactly once in the inventory object or else the API call will return an error code.
  • Provide a tracking_number when submitting a return so the ShipBob staff can quickly identify the return package when it reaches our fulfillment center.
  • Only include inventory items to the return record that will be returned in the same box.
    Example: If inventory_id 12232 and inventory_id 12039 will be returned in two separate boxes, two return orders should be created.
  • ShipBob does not process returns for digital items or bundle inventory items. Return calls that include Digital inventory items (e.g., ebooks), or Bundle inventory items (e.g., multipacks or combinations of multiple items) will return an error code.
  • If you choose to provide a requested action (this is an optional field), only provide one requested action per inventory item. If you don’t provide a requested action, it will default to the action the User set for that inventory item in the ShipBob Merchant Portal.
    If you have more than one quantity of a given item being returned within the same box, all quantities must have the same action associated with them.

Authorizations

​
Authorization
string
header
required

Authentication using Personal Access Token (PAT) token

Headers

​
shipbob_channel_id
string<int32>
required

Channel Id for operation

​
creationSourceId
number<int32>

Body

application/json

The return order creation request containing return details, items, and configuration.

​
fulfillment_center
object
​
inventory
object[] | null
​
original_shipment_id
integer<int32> | null
​
reference_id
string | null
​
tracking_number
string | null

Response

Success

​
channel
object
​
completed_date
string<date-time> | null
​
customer_name
string | null
​
fulfillment_center
object
​
id
integer<int32>
​
insert_date
string<date-time>
​
inventory
object[] | null
​
invoice_amount
number<double> | null
​
original_shipment_id
integer<int32> | null
​
reference_id
string | null
​
return_type
string | null
​
status
string | null
​
store_order_id
string | null
​
tracking_number
string | null
​
transactions
object[] | null