API ReferenceReturns

Create Return Order

View as Markdown

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.

Authentication

AuthorizationBearer

Authentication using Personal Access Token (PAT) token

OR
AuthorizationBearer
OAuth2 authentication using JWT tokens

Headers

shipbob_channel_idstringRequiredformat: "int32"

Retrieve your channel ID from the GET /channel endpoint. Use the channel ID that has write scopes.

Query parameters

api-versionstringOptionalDefaults to 1.0
The requested API version

Request

fulfillment_centerobjectRequired
A Facility to process Returns.
inventorylist of objectsRequired
Array of inventory items being returned
reference_idstringRequired<=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

label_formatenumOptional

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_idintegerOptional

Shipment from which the items in the return originated. Required when purchase_label is true

purchase_labelbooleanOptionalDefaults to false

If true, purchases a return shipping label after creating the return order. Requires original_shipment_id

shipping_servicestringOptional

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_numberstringOptional<=500 characters
Tracking number for the return shipment

Response

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.

labelobject or null

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_errorstring

Human-readable error message if label purchase was requested but failed. The return is still created in this case — only the label step failed.

returnobject
The created return order details

Errors

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