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

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 stringsOptional
Carrier barcode values from label purchase. Currently null in V1
carrierstringOptional

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

carrier_servicestringOptional

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

label_request_idlongOptional
Unique identifier for this label purchase.
label_urlstringOptional

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_urlstringOptional
URL to download the shipping label in ZPL format for thermal printers
purchase_datedatetimeOptional
Date and time when the label was purchased
qrcode_urlstringOptional

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

ratelist of objectsOptional
Shipping rate details including amount and currency
return_idintegerOptional
The ID of the return order this label was purchased for
shipment_rate_idlongOptional
Unique identifier for the shipment rate from the labeling service
tracking_numberstringOptional
Carrier tracking number for the return shipment
tracking_urlstringOptional
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