For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DocumentationAPI Reference
DocumentationAPI Reference
  • API Reference
      • GETGet Return Order
      • PUTEdit Return Order
      • POSTCancel Return order
      • GETGet Return Orders
      • POSTCreate Return Order
LogoLogo
API ReferenceReturns

Create Return Order

||View as Markdown|
POST
https://sandbox-api.shipbob.com/2026-01/return
POST
/2026-01/return
$curl -X POST https://sandbox-api.shipbob.com/2026-01/return \
>     -H "shipbob_channel_id: 1" \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "fulfillment_center": {
>    "id": 0,
>    "name": "string"
>  },
>  "inventory": [
>    {
>      "id": 0,
>      "quantity": 0,
>      "requested_action": "Default",
>      "lot_date": "2019-08-24T14:15:22+00:00",
>      "lot_number": "string"
>    }
>  ],
>  "reference_id": "string",
>  "original_shipment_id": 0,
>  "tracking_number": "string"
>}'
1{
2  "channel": {
3    "id": 0,
4    "name": "string"
5  },
6  "completed_date": "2019-08-24T14:15:22+00:00",
7  "customer_name": "string",
8  "fulfillment_center": {
9    "id": 0,
10    "name": "string"
11  },
12  "id": 0,
13  "insert_date": "2019-08-24T14:15:22+00:00",
14  "inventory": [
15    {
16      "action_requested": {
17        "action": "string",
18        "action_type": "string",
19        "instructions": "string"
20      },
21      "action_taken": [
22        {
23          "action": "string",
24          "action_reason": "string",
25          "image_url": "http://example.com",
26          "quantity_processed": 0
27        }
28      ],
29      "id": 0,
30      "name": "string",
31      "quantity": 0
32    }
33  ],
34  "invoice_amount": 0.1,
35  "original_shipment_id": 0,
36  "reference_id": "string",
37  "return_type": "string",
38  "status": "string",
39  "store_order_id": "string",
40  "tracking_number": "string",
41  "transactions": [
42    {
43      "amount": 0.1,
44      "transaction_type": "string"
45    }
46  ]
47}
Creates a new return order for a previously shipped order. Specify the original shipment, inventory items to return, and requested return actions.
Was this page helpful?
Previous

Get Return Orders

Next

Delete Subscription

Built with

Authentication

AuthorizationBearer

Authentication using Personal Access Token (PAT) token

OR
AuthorizationBearer
OAuth2 authentication using JWT tokens

Headers

shipbob_channel_idintegerRequired
Channel Id for operation

Request

The return order creation request containing return details, items, and configuration.
fulfillment_centerobjectRequired
A Facility to process Returns.
inventorylist of objectsRequired
Array of inventory items being returned
reference_idstringRequired1-50 characters

Client-defined external unique identifier for the return order. If tracking id is not provided, this value must appear on the box label as RMA. Example: ShipBob_Return_123

original_shipment_idintegerOptional

Shipment from which the items in the return originated 123456

tracking_numberstringOptional<=500 characters

Tracking number for the return shipment 1Z9999999999999999

Response

Created
channelobject
The details of a Channel
completed_datedatetime
The date and time for when the return order was completely processed
customer_namestring
Name of merchant that return belongs to
fulfillment_centerobject
The details of a Fulfillment Center
idinteger
Unique id of the return order
insert_datedatetime
The date and time for when the return order was created
inventorylist of objects
List of inventory items in return order
invoice_amountdouble
Amount merchant was invoiced for processing the return
original_shipment_idinteger
ShipmentId for which return was created
reference_idstring
Unique reference id of the return order. Created by merchant if a regular return.
return_typestring
Type of the return, i.e. Regular, RTS
statusstring

Status of the return order, i.e. Awaiting Arrival, Arrived, Processing, Completed Cancelled

store_order_idstring
Reference to external order id
tracking_numberstring
The tracking number of the return shipping label
transactionslist of objects
List of transactions that make up the billable amount to invoice a merchant

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
422
Unprocessable Entity Error