> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer-dev.shipbob.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-dev.shipbob.dev/_mcp/server. # Create Return Order POST https://gateway-dev.shipbob.dev/Experimental/return Content-Type: application/json Creates a new return order for a previously shipped order. Specify the original shipment, inventory items to return, and requested return actions. If purchase_label is true, also purchases a return shipping label using the original_shipment_id. Reference: https://developer-dev.shipbob.dev/api/returns/create-return-order ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: api-experimental version: 1.0.0 paths: /Experimental/return: post: operationId: create-return-order summary: | Create Return Order description: > Creates a new return order for a previously shipped order. Specify the original shipment, inventory items to return, and requested return actions. If purchase_label is true, also purchases a return shipping label using the original_shipment_id. tags: - returns parameters: - name: api-version in: query description: | The requested API version required: false schema: type: string - name: Authorization in: header description: Authentication using Personal Access Token (PAT) token required: true schema: type: string - name: shipbob_channel_id in: header description: >- Retrieve your channel ID from the [GET /channel](/api/channels/get-channels) endpoint. Use the channel ID that has write scopes. required: true schema: type: string format: int32 responses: '201': description: >- Return order created successfully. When purchase_label is true and the label purchase succeeds, both return and label are populated. When purchase_label is false, only return is populated. When purchase_label is true but the label purchase fails, return is populated, label is null, and label_error explains the failure. content: application/json: schema: $ref: '#/components/schemas/Returns.CreateReturnWithLabelResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Returns.ProblemDetails' '401': description: Authorization missing or invalid content: application/json: schema: description: Any type '403': description: The provided credentials are not authorized to access this resource content: application/json: schema: description: Any type '422': description: Validation failed content: application/json: schema: $ref: '#/components/schemas/Returns.ProblemDetails' requestBody: content: application/json: schema: $ref: '#/components/schemas/Returns.CreateReturnRequest' servers: - url: https://gateway-dev.shipbob.dev description: https://gateway-dev.shipbob.dev components: schemas: Returns.Facility: type: object properties: id: type: integer description: Unique identifier of the facility name: type: - string - 'null' description: >- Name of the facility (It is optional because public API integrations do not pass this) description: A Facility to process Returns. title: Returns.Facility Returns.ReturnAction: type: string enum: - Default - Restock - Quarantine - Dispose - Donation title: Returns.ReturnAction Returns.ReturnInventory: type: object properties: id: type: integer description: ID of the inventory item to return. lot_date: type: - string - 'null' format: date-time description: Lot date associated with the inventory item, if applicable. lot_number: type: - string - 'null' description: Lot number associated with the inventory item, if applicable. quantity: type: integer description: Quantity of the returned inventory item in the return. requested_action: $ref: '#/components/schemas/Returns.ReturnAction' required: - id - quantity - requested_action description: >- An inventory being returned, includes the quantity and an override for the return action. title: Returns.ReturnInventory ReturnsCreateReturnRequestLabelFormat: type: string enum: - PDF - PNG description: >- Optional label file format. Accepted values: PDF, PNG. If not provided, carrier default format is used. Only used when purchase_label is true title: ReturnsCreateReturnRequestLabelFormat Returns.CreateReturnRequest: type: object properties: fulfillment_center: $ref: '#/components/schemas/Returns.Facility' inventory: type: array items: $ref: '#/components/schemas/Returns.ReturnInventory' description: Array of inventory items being returned label_format: oneOf: - $ref: '#/components/schemas/ReturnsCreateReturnRequestLabelFormat' - type: 'null' description: >- Optional label file format. Accepted values: PDF, PNG. If not provided, carrier default format is used. Only used when purchase_label is true original_shipment_id: type: - integer - 'null' description: >- Shipment from which the items in the return originated. Required when purchase_label is true purchase_label: type: - boolean - 'null' default: false description: >- If true, purchases a return shipping label after creating the return order. Requires original_shipment_id reference_id: type: string description: >- 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 shipping_service: type: - string - 'null' description: >- Ship option name (e.g. "ReturnsStandard") for label purchase. Only used when purchase_label is true. Resolved against available return ship options for the merchant. Falls back to cheapest if not matched tracking_number: type: - string - 'null' description: Tracking number for the return shipment required: - fulfillment_center - inventory - reference_id description: The request payload for creating a Return of inventory. title: Returns.CreateReturnRequest Returns.RateInfo: type: object properties: amount: type: - integer - 'null' format: int64 description: >- Shipping rate amount in cents (e.g. 850 = $8.50). Null when the merchant-facing rate is not known for the return. currency_code: type: - string - 'null' description: >- ISO 4217 currency code (e.g. USD). Null when the merchant-facing rate is not known for the return. description: Shipping rate amount and currency details. title: Returns.RateInfo Returns.CreateReturnLabelResponse: type: object properties: barcode: type: - array - 'null' items: type: string description: Carrier barcode values from label purchase. Currently null in V1 carrier: type: string description: Name of the shipping carrier (e.g. USPS, UPS, FedEx) carrier_service: type: string description: Specific carrier service used (e.g. Ground Advantage, Priority Mail) label_request_id: type: - integer - 'null' format: int64 description: Unique identifier for this label purchase. label_url: type: string description: >- URL to download the shipping label image. Format follows the label_format request parameter (PDF or PNG) when the carrier supports it; otherwise the carrier's default format is returned. label_zpl_url: type: - string - 'null' description: >- URL to download the shipping label in ZPL format for thermal printers purchase_date: type: string format: date-time description: Date and time when the label was purchased qrcode_url: type: - string - 'null' description: QR code image URL for label-less returns. Currently null in V1 rate: type: array items: $ref: '#/components/schemas/Returns.RateInfo' description: Shipping rate details including amount and currency return_id: type: integer description: The ID of the return order this label was purchased for shipment_rate_id: type: integer format: int64 description: Unique identifier for the shipment rate from the labeling service tracking_number: type: string description: Carrier tracking number for the return shipment tracking_url: type: - string - 'null' description: URL to track the return shipment on the carrier website description: >- Return shipping label details including tracking number, label URL, carrier information, and rate. title: Returns.CreateReturnLabelResponse Returns.ChannelDto: type: object properties: id: type: integer description: Unique Id of the channel name: type: - string - 'null' description: Name given to the channel description: The details of a Channel title: Returns.ChannelDto Returns.FulfillmentCenterDto: type: object properties: id: type: integer description: Unique id of the fulfillment center name: type: - string - 'null' description: Name give to the fulfillment center description: The details of a Fulfillment Center title: Returns.FulfillmentCenterDto Returns.ActionRequestedDto: type: object properties: action: type: - string - 'null' description: The action to take action_type: type: - string - 'null' description: >- The source of the action to take, i.e. Inventory Default or Overriden by Merchant at creation instructions: type: - string - 'null' description: >- The instructions for how to take the action given by inventory owning Merchant description: The details of the action requested for inventory title: Returns.ActionRequestedDto Returns.ActionTakenDto: type: object properties: action: type: - string - 'null' description: The return action taken action_reason: type: - string - 'null' description: The reason the action was taken image_url: type: - string - 'null' format: uri description: Image of inventory processed with this action. quantity_processed: type: integer description: >- The quantity of inventory items processed with this reason and action description: The details of an action taken for inventory item in the return title: Returns.ActionTakenDto Returns.LotInformationDto: type: object properties: expiration: type: - string - 'null' format: date-time description: The expiration date for this lot. minimumShelfLife: type: - integer - 'null' description: >- A minimum amount of time in days this product can be safely returned to the shelf without expiring. number: type: - string - 'null' description: >- An alphanumeric string uniquely identifying this lot of produced inventory. description: Lot information associated with a specific inventory item. title: Returns.LotInformationDto Returns.InventoryItemDto: type: object properties: action_requested: $ref: '#/components/schemas/Returns.ActionRequestedDto' action_taken: type: - array - 'null' items: $ref: '#/components/schemas/Returns.ActionTakenDto' description: List of actions taken barcodes: type: - array - 'null' items: type: string description: List of barcodes associated with the inventory item bundle_parent_sku: type: - string - 'null' description: >- SKU of the parent bundle if this item was expanded from a bundle. Null for non-bundle items id: type: integer description: Unique id of the inventory lot_information: oneOf: - $ref: '#/components/schemas/Returns.LotInformationDto' - type: 'null' name: type: - string - 'null' description: Name of the product quantity: type: integer description: Number of inventory that is being returned sku: type: - string - 'null' description: Stock keeping unit identifier for the inventory item description: The details of the inventory in the return order title: Returns.InventoryItemDto Returns.InvoiceDto: type: object properties: amount: type: - number - 'null' format: double description: Amount being charged currency_code: type: - string - 'null' description: Currency code of amount description: The invoice amount and curency title: Returns.InvoiceDto Returns.StatusHistoryDto: type: object properties: status: type: - string - 'null' description: Status to change timestamp: type: string format: date-time description: Date change status description: Status history title: Returns.StatusHistoryDto Returns.TransactionDto: type: object properties: amount: type: number format: double description: The amount charged for this transaction transaction_type: type: - string - 'null' description: The type of transaction description: The details of a transaction charged to the return order title: Returns.TransactionDto Returns.PublicReturnDto: type: object properties: arrived_date: type: - string - 'null' format: date-time description: The date and time when the return arrived at the fulfillment center awaiting_arrival_date: type: - string - 'null' format: date-time description: The date and time when the return entered Awaiting Arrival status cancelled_date: type: - string - 'null' format: date-time description: The date and time when the return was cancelled, if applicable channel: $ref: '#/components/schemas/Returns.ChannelDto' completed_date: type: - string - 'null' format: date-time description: The date and time for when the return order was completely processed customer_name: type: - string - 'null' description: Name of merchant that return belongs to fulfillment_center: $ref: '#/components/schemas/Returns.FulfillmentCenterDto' id: type: integer description: Unique id of the return order insert_date: type: string format: date-time description: The date and time for when the return order was created inventory: type: - array - 'null' items: $ref: '#/components/schemas/Returns.InventoryItemDto' description: List of inventory items in return order invoice: oneOf: - $ref: '#/components/schemas/Returns.InvoiceDto' - type: 'null' original_shipment_id: type: - integer - 'null' description: ShipmentId for which return was created processing_date: type: - string - 'null' format: date-time description: The date and time when the return started processing reference_id: type: - string - 'null' description: >- Unique reference id of the return order. Created by merchant if a regular return. return_type: type: - string - 'null' description: Type of the return, i.e. Regular, RTS shipment_tracking_number: type: - string - 'null' description: The tracking number of the original shipment status: type: - string - 'null' description: >- Status of the return order, i.e. `Awaiting Arrival`, `Arrived`, `Processing`, `Completed` `Cancelled` status_history: type: - array - 'null' items: $ref: '#/components/schemas/Returns.StatusHistoryDto' description: List of status history in return order store_order_id: type: - string - 'null' description: Reference to external order id tracking_number: type: - string - 'null' description: The tracking number of the return shipping label transactions: type: - array - 'null' items: $ref: '#/components/schemas/Returns.TransactionDto' description: >- List of transactions that make up the billable amount to invoice a merchant description: >- The details of a public return order, including the transactions and inventory items title: Returns.PublicReturnDto Returns.CreateReturnWithLabelResponse: type: object properties: label: oneOf: - $ref: '#/components/schemas/Returns.CreateReturnLabelResponse' - type: 'null' description: >- Return shipping label details. Populated only when purchase_label is true and the label purchase succeeded. Null when purchase_label is false or the label purchase failed (in which case label_error explains why). label_error: type: - string - 'null' description: >- Human-readable error message if label purchase was requested but failed. The return is still created in this case — only the label step failed. return: $ref: '#/components/schemas/Returns.PublicReturnDto' description: The created return order details description: >- Response from creating a return order. When purchase_label is true and the label purchase succeeds, both return and label are populated. When purchase_label is false, only return is populated. When purchase_label is true but the label purchase fails, return is populated, label is null, and label_error explains the failure. title: Returns.CreateReturnWithLabelResponse Returns.ProblemDetails: type: object properties: detail: type: - string - 'null' description: >- Human-readable explanation specific to this occurrence of the problem. instance: type: - string - 'null' description: URI reference identifying the specific occurrence. status: type: - integer - 'null' description: HTTP status code. title: type: - string - 'null' description: Short, human-readable summary of the problem. type: type: - string - 'null' description: URI reference identifying the problem type. description: >- RFC 7807 Problem Details — standard error response body used across ShipBob public APIs. title: Returns.ProblemDetails securitySchemes: PAT: type: http scheme: bearer description: Authentication using Personal Access Token (PAT) token OAuth2: type: http scheme: bearer description: OAuth2 authentication using JWT tokens ``` ## Examples **Request** ```json { "fulfillment_center": { "id": 10, "name": "Cicero (CHI3)" }, "inventory": [ { "id": 1279396, "quantity": 2, "requested_action": "Restock", "lot_date": null, "lot_number": null } ], "reference_id": "RMA-2026-00123", "original_shipment_id": 98765, "purchase_label": true, "shipping_service": "ReturnsStandard", "tracking_number": "1Z999AA10123456784" } ``` **Response** ```json { "label": { "barcode": null, "carrier": "UPS", "carrier_service": "Ground", "label_request_id": 999, "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/label.png", "label_zpl_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/label.zpl", "purchase_date": "2026-04-13T12:00:00+00:00", "qrcode_url": null, "rate": [ { "amount": 1025, "currency_code": "USD" } ], "return_id": 12345, "shipment_rate_id": 999, "tracking_number": "1Z999AA10123456784", "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784" }, "label_error": null, "return": { "arrived_date": null, "awaiting_arrival_date": "2026-04-13T12:00:00+00:00", "cancelled_date": null, "channel": { "id": 1, "name": "ShipBob Default" }, "completed_date": null, "customer_name": "Jane Doe", "fulfillment_center": { "id": 8, "name": "Cicero (IL)" }, "id": 12345, "insert_date": "2026-04-13T12:00:00+00:00", "inventory": [ { "action_requested": { "action": "Restock", "action_type": "InventoryDefault", "instructions": "" }, "action_taken": [], "barcodes": [ "BC-100" ], "id": 100, "lot_information": null, "name": "Test Product", "quantity": 1, "sku": "SKU-100" } ], "invoice": null, "original_shipment_id": 98765, "processing_date": null, "reference_id": "REF-12345", "return_type": "Customer Generated", "shipment_tracking_number": null, "status": "Awaiting Arrival", "status_history": [ { "status": "Awaiting Arrival", "timestamp": "2026-04-13T12:00:00+00:00" } ], "store_order_id": "SO-12345", "tracking_number": null, "transactions": [] } } ``` **SDK Code** ```python default import requests url = "https://gateway-dev.shipbob.dev/Experimental/return" querystring = {"api-version":"1"} payload = { "fulfillment_center": { "id": 10, "name": "Cicero (CHI3)" }, "inventory": [ { "id": 1279396, "quantity": 2, "requested_action": "Restock", "lot_date": None, "lot_number": None } ], "reference_id": "RMA-2026-00123", "original_shipment_id": 98765, "purchase_label": True, "shipping_service": "ReturnsStandard", "tracking_number": "1Z999AA10123456784" } headers = { "shipbob_channel_id": "shipbob_channel_id", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript default const url = 'https://gateway-dev.shipbob.dev/Experimental/return?api-version=1'; const options = { method: 'POST', headers: { shipbob_channel_id: 'shipbob_channel_id', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"fulfillment_center":{"id":10,"name":"Cicero (CHI3)"},"inventory":[{"id":1279396,"quantity":2,"requested_action":"Restock","lot_date":null,"lot_number":null}],"reference_id":"RMA-2026-00123","original_shipment_id":98765,"purchase_label":true,"shipping_service":"ReturnsStandard","tracking_number":"1Z999AA10123456784"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go default package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://gateway-dev.shipbob.dev/Experimental/return?api-version=1" payload := strings.NewReader("{\n \"fulfillment_center\": {\n \"id\": 10,\n \"name\": \"Cicero (CHI3)\"\n },\n \"inventory\": [\n {\n \"id\": 1279396,\n \"quantity\": 2,\n \"requested_action\": \"Restock\",\n \"lot_date\": null,\n \"lot_number\": null\n }\n ],\n \"reference_id\": \"RMA-2026-00123\",\n \"original_shipment_id\": 98765,\n \"purchase_label\": true,\n \"shipping_service\": \"ReturnsStandard\",\n \"tracking_number\": \"1Z999AA10123456784\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("shipbob_channel_id", "shipbob_channel_id") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby default require 'uri' require 'net/http' url = URI("https://gateway-dev.shipbob.dev/Experimental/return?api-version=1") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["shipbob_channel_id"] = 'shipbob_channel_id' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"fulfillment_center\": {\n \"id\": 10,\n \"name\": \"Cicero (CHI3)\"\n },\n \"inventory\": [\n {\n \"id\": 1279396,\n \"quantity\": 2,\n \"requested_action\": \"Restock\",\n \"lot_date\": null,\n \"lot_number\": null\n }\n ],\n \"reference_id\": \"RMA-2026-00123\",\n \"original_shipment_id\": 98765,\n \"purchase_label\": true,\n \"shipping_service\": \"ReturnsStandard\",\n \"tracking_number\": \"1Z999AA10123456784\"\n}" response = http.request(request) puts response.read_body ``` ```java default import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://gateway-dev.shipbob.dev/Experimental/return?api-version=1") .header("shipbob_channel_id", "shipbob_channel_id") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"fulfillment_center\": {\n \"id\": 10,\n \"name\": \"Cicero (CHI3)\"\n },\n \"inventory\": [\n {\n \"id\": 1279396,\n \"quantity\": 2,\n \"requested_action\": \"Restock\",\n \"lot_date\": null,\n \"lot_number\": null\n }\n ],\n \"reference_id\": \"RMA-2026-00123\",\n \"original_shipment_id\": 98765,\n \"purchase_label\": true,\n \"shipping_service\": \"ReturnsStandard\",\n \"tracking_number\": \"1Z999AA10123456784\"\n}") .asString(); ``` ```php default request('POST', 'https://gateway-dev.shipbob.dev/Experimental/return?api-version=1', [ 'body' => '{ "fulfillment_center": { "id": 10, "name": "Cicero (CHI3)" }, "inventory": [ { "id": 1279396, "quantity": 2, "requested_action": "Restock", "lot_date": null, "lot_number": null } ], "reference_id": "RMA-2026-00123", "original_shipment_id": 98765, "purchase_label": true, "shipping_service": "ReturnsStandard", "tracking_number": "1Z999AA10123456784" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'shipbob_channel_id' => 'shipbob_channel_id', ], ]); echo $response->getBody(); ``` ```csharp default using RestSharp; var client = new RestClient("https://gateway-dev.shipbob.dev/Experimental/return?api-version=1"); var request = new RestRequest(Method.POST); request.AddHeader("shipbob_channel_id", "shipbob_channel_id"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"fulfillment_center\": {\n \"id\": 10,\n \"name\": \"Cicero (CHI3)\"\n },\n \"inventory\": [\n {\n \"id\": 1279396,\n \"quantity\": 2,\n \"requested_action\": \"Restock\",\n \"lot_date\": null,\n \"lot_number\": null\n }\n ],\n \"reference_id\": \"RMA-2026-00123\",\n \"original_shipment_id\": 98765,\n \"purchase_label\": true,\n \"shipping_service\": \"ReturnsStandard\",\n \"tracking_number\": \"1Z999AA10123456784\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift default import Foundation let headers = [ "shipbob_channel_id": "shipbob_channel_id", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "fulfillment_center": [ "id": 10, "name": "Cicero (CHI3)" ], "inventory": [ [ "id": 1279396, "quantity": 2, "requested_action": "Restock", "lot_date": , "lot_number": ] ], "reference_id": "RMA-2026-00123", "original_shipment_id": 98765, "purchase_label": true, "shipping_service": "ReturnsStandard", "tracking_number": "1Z999AA10123456784" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://gateway-dev.shipbob.dev/Experimental/return?api-version=1")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```