Skip to main content
POST
/
2.0
/
return
Create Return Order 
curl --request POST \
  --url https://api.shipbob.com/2.0/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_shipmentId": 0,
  "reference_id": "string",
  "tracking_number": "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 Awaiting Arrival status. Returns that are being Processed or have been Completed cannot be modified or cancelled.

​
Tips for Creating Return Orders

  • Populate the referenceId 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 inventoryId exactly once in the inventory object. If an inventoryId is included more than once, the call will return an error code.
  • Provide a tracking number when submitting a return. While it is not a required field, it is the most surefire way for ShipBob staff to properly and 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 InventoryId 12232 and InventoryId 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 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.
    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.

Authorizations

​
Authorization
string
header
required

Authentication using Personal Access Token (PAT) token

Headers

​
shipbob_channel_id
string<int32>
required
​
creationSourceId
number<int32>

Body

application/json
​
fulfillment_center
object
​
inventory
object[] | null
​
original_shipmentId
integer<int32> | null
​
reference_id
string | null
​
tracking_number
string | null

Response

Success