API ReferenceReturns

Create Return Label

View as MarkdownOpen in Claude

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_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

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. Either shipment_id or origin_address must be provided.

shipment_idintegerOptional

Original outbound shipment ID. If provided, origin address is extracted from the shipment record. Either shipment_id or origin_address must be provided.

shipping_servicestringOptional

Ship option name (e.g. “ReturnsStandard”). Resolved against available return ship options for the merchant. 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 identifier for this label purchase.
label_urlstring

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_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