API ReferenceReturns

Create Return Label

View as Markdown

Purchases a return shipping label for an existing return order. If a label has already been purchased, returns the existing label data (200 OK). Otherwise purchases a new label and returns it (201 Created).

Authentication

AuthorizationBearer

Authentication using Personal Access Token (PAT) token

OR
AuthorizationBearer
OAuth2 authentication using JWT tokens

Path parameters

idintegerRequired
The unique identifier of the return order to purchase a label for

Headers

shipbob_channel_idintegerRequired
The unique identifier of the channel to scope this request to

Query parameters

api-versionstringOptionalDefaults to 1.0
The requested API version

Request

label_formatenumOptional

Optional label file format. Accepted values: PDF, PNG. If not provided, carrier default format is used

Allowed values:
origin_addressobjectOptional

Customer return address. Required if shipment_id is not provided

shipment_idintegerOptional
Original outbound shipment ID. If provided, origin address is extracted from the shipment record
shipping_servicestringOptional

Ship option name (e.g. “UPS Ground”). Resolved against available return ship options. Falls back to cheapest available option if not matched

Response

Label already purchased — returns existing label data

barcodelist of strings
Carrier barcode values from label purchase. Currently null in V1
carrierstring

Name of the shipping carrier (e.g. USPS, UPS, FedEx)

carrier_servicestring

Specific carrier service used (e.g. Ground Advantage, Priority Mail)

label_request_idlong
Unique label purchase identifier, maps to ShipmentRateId from LabelingService
label_urlstring
URL to download the shipping label as PDF
label_zpl_urlstring
URL to download the shipping label in ZPL format for thermal printers
purchase_datedatetime
Date and time when the label was purchased
qrcode_urlstring

QR code image URL for label-less returns. Currently null in V1

ratelist of objects
Shipping rate details including amount and currency
return_idinteger
The ID of the return order this label was purchased for
shipment_rate_idlong
Unique identifier for the shipment rate from the labeling service
tracking_numberstring
Carrier tracking number for the return shipment
tracking_urlstring
URL to track the return shipment on the carrier website

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error