Create Return Order | ShipBob Developer API

curl -X POST https://api.shipbob.com/2026-07/return \
     -H "shipbob_channel_id: shipbob_channel_id" \
     -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"
}'

{
  "channel": {
    "id": 0,
    "name": "string"
  },
  "completed_date": "2019-08-24T14:15:22+00:00",
  "customer_name": "string",
  "fulfillment_center": {
    "id": 0,
    "name": "string"
  },
  "id": 0,
  "insert_date": "2019-08-24T14:15:22+00:00",
  "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"
    }
  ]
}

Creates a new return order for a previously shipped order. Specify the original shipment, inventory items to return, and requested return actions.

Authentication

AuthorizationBearer

Authentication using Personal Access Token (PAT) token

AuthorizationBearer

OAuth2 authentication using JWT tokens

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_idinteger or nullOptional

Shipment from which the items in the return originated 123456

tracking_numberstring or nullOptional<=500 characters

Tracking number for the return shipment 1Z9999999999999999

Response

Created

channelobjectOptional

The details of a Channel

completed_datedatetime or nullOptional

The date and time for when the return order was completely processed

customer_namestring or nullOptional

Name of merchant that return belongs to

fulfillment_centerobjectOptional

The details of a Fulfillment Center

idintegerOptional

Unique id of the return order

insert_datedatetimeOptional

The date and time for when the return order was created

inventorylist of objects or nullOptional

List of inventory items in return order

invoice_amountdouble or nullOptional

Amount merchant was invoiced for processing the return

original_shipment_idinteger or nullOptional

ShipmentId for which return was created

reference_idstring or nullOptional

Unique reference id of the return order. Created by merchant if a regular return.

return_typestring or nullOptional

Type of the return, i.e. Regular, RTS

statusstring or nullOptional

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

store_order_idstring or nullOptional

Reference to external order id

tracking_numberstring or nullOptional

The tracking number of the return shipping label

transactionslist of objects or nullOptional

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

Authentication

Headers

Request

Response

Errors