> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer-stage.shipbob.dev/experimental/api/returns/llms.txt. > For full documentation content, see https://developer-stage.shipbob.dev/experimental/api/returns/llms-full.txt. # Create Return Label POST https://sandbox-api.shipbob.com/Experimental/return/{id}/label Content-Type: application/json 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). Reference: https://developer-stage.shipbob.dev/experimental/api/returns/create-return-label ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: api-experimental version: 1.0.0 paths: /Experimental/return/{id}/label: post: operationId: create-return-label summary: | Create Return Label description: > 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). tags: - subpackage_returns parameters: - name: id in: path description: The unique identifier of the return order to purchase a label for required: true schema: $ref: >- #/components/schemas/Returns.Post.Api.Experimental.Return.Id.Label.Id.Integer - name: api-version in: query description: | The requested API version required: false schema: $ref: >- #/components/schemas/Returns.Post.Api.Experimental.Return.Id.Label.Api.Version.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: The unique identifier of the channel to scope this request to required: true schema: $ref: >- #/components/schemas/Returns.Post.Api.Experimental.Return.Id.Label.Shipbob.Channel.Id.Integer responses: '200': description: Label already purchased — returns existing label data content: application/json: schema: $ref: '#/components/schemas/Returns.CreateReturnLabelResponse' '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 '404': description: Return order not found content: application/json: schema: $ref: '#/components/schemas/Returns.ProblemDetails' '422': description: >- Validation failed (e.g. missing address, cancelled return, hazmat item) content: application/json: schema: $ref: '#/components/schemas/Returns.ProblemDetails' requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/Returns.CreateReturnLabelRequest' servers: - url: https://sandbox-api.shipbob.com components: schemas: Returns.Post.Api.Experimental.Return.Id.Label.Id.Integer: type: integer description: The unique identifier of the return order title: Returns.Post.Api.Experimental.Return.Id.Label.Id.Integer Returns.Post.Api.Experimental.Return.Id.Label.Api.Version.String: type: string default: '1.0' title: Returns.Post.Api.Experimental.Return.Id.Label.Api.Version.String Returns.Post.Api.Experimental.Return.Id.Label.Shipbob.Channel.Id.Integer: type: integer description: The unique identifier of the channel to scope this request to title: Returns.Post.Api.Experimental.Return.Id.Label.Shipbob.Channel.Id.Integer ReturnsCreateReturnLabelRequestLabelFormat: type: string enum: - PDF - PNG description: >- Optional label file format. Accepted values: PDF, PNG. If not provided, carrier default format is used title: ReturnsCreateReturnLabelRequestLabelFormat Returns.ReturnLabelAddress: type: object properties: city: type: string description: City name company: type: string description: Company or business name country: type: string description: ISO 3166-1 alpha-2 country code (e.g. US, CA, GB) email: type: string description: Contact email address name: type: string description: Full name of the person at the return origin address phone: type: string description: Contact phone number state: type: string description: State or province code (e.g. IL, NY, CA) street1: type: string description: Primary street address line street2: type: string description: Secondary street address line (apartment, suite, unit, etc.) zip_code: type: string description: Postal or ZIP code description: >- Customer address used as the origin (from) address on the return shipping label. title: Returns.ReturnLabelAddress Returns.CreateReturnLabelRequest: type: object properties: label_format: $ref: '#/components/schemas/ReturnsCreateReturnLabelRequestLabelFormat' description: >- Optional label file format. Accepted values: PDF, PNG. If not provided, carrier default format is used origin_address: $ref: '#/components/schemas/Returns.ReturnLabelAddress' description: Customer return address. Required if shipment_id is not provided shipment_id: type: integer description: >- Original outbound shipment ID. If provided, origin address is extracted from the shipment record shipping_service: type: string description: >- Ship option name (e.g. "UPS Ground"). Resolved against available return ship options. Falls back to cheapest available option if not matched description: >- Request to purchase a return shipping label for an existing return order. title: Returns.CreateReturnLabelRequest Returns.RateInfo: type: object properties: amount: type: integer format: int64 description: Shipping rate amount in cents (e.g. 850 = $8.50) currency_code: type: string description: ISO 4217 currency code (e.g. USD) description: Shipping rate amount and currency details. title: Returns.RateInfo Returns.CreateReturnLabelResponse: type: object properties: barcode: type: array 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 format: int64 description: >- Unique label purchase identifier, maps to ShipmentRateId from LabelingService label_url: type: string description: URL to download the shipping label as PDF label_zpl_url: type: string 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 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 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.ProblemDetails: type: object properties: detail: type: string instance: type: string status: type: integer title: type: string type: type: string 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 ``` ## SDK Code Examples ```python default import requests url = "https://sandbox-api.shipbob.com/Experimental/return/1/label" querystring = {"api-version":"1"} payload = { "origin_address": { "city": "Chicago", "company": "ACME Corp", "country": "US", "email": "jane@example.com", "name": "Jane Doe", "phone": "312-555-0100", "state": "IL", "street1": "123 Main St", "street2": "Apt 4B", "zip_code": "60601" }, "shipment_id": 98765, "shipping_service": "UPS Ground" } headers = { "shipbob_channel_id": "1", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript default const url = 'https://sandbox-api.shipbob.com/Experimental/return/1/label?api-version=1'; const options = { method: 'POST', headers: { shipbob_channel_id: '1', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"origin_address":{"city":"Chicago","company":"ACME Corp","country":"US","email":"jane@example.com","name":"Jane Doe","phone":"312-555-0100","state":"IL","street1":"123 Main St","street2":"Apt 4B","zip_code":"60601"},"shipment_id":98765,"shipping_service":"UPS Ground"}' }; 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://sandbox-api.shipbob.com/Experimental/return/1/label?api-version=1" payload := strings.NewReader("{\n \"origin_address\": {\n \"city\": \"Chicago\",\n \"company\": \"ACME Corp\",\n \"country\": \"US\",\n \"email\": \"jane@example.com\",\n \"name\": \"Jane Doe\",\n \"phone\": \"312-555-0100\",\n \"state\": \"IL\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip_code\": \"60601\"\n },\n \"shipment_id\": 98765,\n \"shipping_service\": \"UPS Ground\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("shipbob_channel_id", "1") 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://sandbox-api.shipbob.com/Experimental/return/1/label?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"] = '1' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"origin_address\": {\n \"city\": \"Chicago\",\n \"company\": \"ACME Corp\",\n \"country\": \"US\",\n \"email\": \"jane@example.com\",\n \"name\": \"Jane Doe\",\n \"phone\": \"312-555-0100\",\n \"state\": \"IL\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip_code\": \"60601\"\n },\n \"shipment_id\": 98765,\n \"shipping_service\": \"UPS Ground\"\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://sandbox-api.shipbob.com/Experimental/return/1/label?api-version=1") .header("shipbob_channel_id", "1") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"origin_address\": {\n \"city\": \"Chicago\",\n \"company\": \"ACME Corp\",\n \"country\": \"US\",\n \"email\": \"jane@example.com\",\n \"name\": \"Jane Doe\",\n \"phone\": \"312-555-0100\",\n \"state\": \"IL\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip_code\": \"60601\"\n },\n \"shipment_id\": 98765,\n \"shipping_service\": \"UPS Ground\"\n}") .asString(); ``` ```php default request('POST', 'https://sandbox-api.shipbob.com/Experimental/return/1/label?api-version=1', [ 'body' => '{ "origin_address": { "city": "Chicago", "company": "ACME Corp", "country": "US", "email": "jane@example.com", "name": "Jane Doe", "phone": "312-555-0100", "state": "IL", "street1": "123 Main St", "street2": "Apt 4B", "zip_code": "60601" }, "shipment_id": 98765, "shipping_service": "UPS Ground" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'shipbob_channel_id' => '1', ], ]); echo $response->getBody(); ``` ```csharp default using RestSharp; var client = new RestClient("https://sandbox-api.shipbob.com/Experimental/return/1/label?api-version=1"); var request = new RestRequest(Method.POST); request.AddHeader("shipbob_channel_id", "1"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"origin_address\": {\n \"city\": \"Chicago\",\n \"company\": \"ACME Corp\",\n \"country\": \"US\",\n \"email\": \"jane@example.com\",\n \"name\": \"Jane Doe\",\n \"phone\": \"312-555-0100\",\n \"state\": \"IL\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip_code\": \"60601\"\n },\n \"shipment_id\": 98765,\n \"shipping_service\": \"UPS Ground\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift default import Foundation let headers = [ "shipbob_channel_id": "1", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "origin_address": [ "city": "Chicago", "company": "ACME Corp", "country": "US", "email": "jane@example.com", "name": "Jane Doe", "phone": "312-555-0100", "state": "IL", "street1": "123 Main St", "street2": "Apt 4B", "zip_code": "60601" ], "shipment_id": 98765, "shipping_service": "UPS Ground" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox-api.shipbob.com/Experimental/return/1/label?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() ``` ```python default import requests url = "https://sandbox-api.shipbob.com/Experimental/return/1/label" querystring = {"api-version":"1"} payload = { "origin_address": { "city": "Chicago", "company": "ACME Corp", "country": "US", "email": "jane@example.com", "name": "Jane Doe", "phone": "312-555-0100", "state": "IL", "street1": "123 Main St", "street2": "Apt 4B", "zip_code": "60601" }, "shipment_id": 98765, "shipping_service": "UPS Ground" } headers = { "shipbob_channel_id": "1", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript default const url = 'https://sandbox-api.shipbob.com/Experimental/return/1/label?api-version=1'; const options = { method: 'POST', headers: { shipbob_channel_id: '1', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"origin_address":{"city":"Chicago","company":"ACME Corp","country":"US","email":"jane@example.com","name":"Jane Doe","phone":"312-555-0100","state":"IL","street1":"123 Main St","street2":"Apt 4B","zip_code":"60601"},"shipment_id":98765,"shipping_service":"UPS Ground"}' }; 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://sandbox-api.shipbob.com/Experimental/return/1/label?api-version=1" payload := strings.NewReader("{\n \"origin_address\": {\n \"city\": \"Chicago\",\n \"company\": \"ACME Corp\",\n \"country\": \"US\",\n \"email\": \"jane@example.com\",\n \"name\": \"Jane Doe\",\n \"phone\": \"312-555-0100\",\n \"state\": \"IL\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip_code\": \"60601\"\n },\n \"shipment_id\": 98765,\n \"shipping_service\": \"UPS Ground\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("shipbob_channel_id", "1") 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://sandbox-api.shipbob.com/Experimental/return/1/label?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"] = '1' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"origin_address\": {\n \"city\": \"Chicago\",\n \"company\": \"ACME Corp\",\n \"country\": \"US\",\n \"email\": \"jane@example.com\",\n \"name\": \"Jane Doe\",\n \"phone\": \"312-555-0100\",\n \"state\": \"IL\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip_code\": \"60601\"\n },\n \"shipment_id\": 98765,\n \"shipping_service\": \"UPS Ground\"\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://sandbox-api.shipbob.com/Experimental/return/1/label?api-version=1") .header("shipbob_channel_id", "1") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"origin_address\": {\n \"city\": \"Chicago\",\n \"company\": \"ACME Corp\",\n \"country\": \"US\",\n \"email\": \"jane@example.com\",\n \"name\": \"Jane Doe\",\n \"phone\": \"312-555-0100\",\n \"state\": \"IL\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip_code\": \"60601\"\n },\n \"shipment_id\": 98765,\n \"shipping_service\": \"UPS Ground\"\n}") .asString(); ``` ```php default request('POST', 'https://sandbox-api.shipbob.com/Experimental/return/1/label?api-version=1', [ 'body' => '{ "origin_address": { "city": "Chicago", "company": "ACME Corp", "country": "US", "email": "jane@example.com", "name": "Jane Doe", "phone": "312-555-0100", "state": "IL", "street1": "123 Main St", "street2": "Apt 4B", "zip_code": "60601" }, "shipment_id": 98765, "shipping_service": "UPS Ground" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'shipbob_channel_id' => '1', ], ]); echo $response->getBody(); ``` ```csharp default using RestSharp; var client = new RestClient("https://sandbox-api.shipbob.com/Experimental/return/1/label?api-version=1"); var request = new RestRequest(Method.POST); request.AddHeader("shipbob_channel_id", "1"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"origin_address\": {\n \"city\": \"Chicago\",\n \"company\": \"ACME Corp\",\n \"country\": \"US\",\n \"email\": \"jane@example.com\",\n \"name\": \"Jane Doe\",\n \"phone\": \"312-555-0100\",\n \"state\": \"IL\",\n \"street1\": \"123 Main St\",\n \"street2\": \"Apt 4B\",\n \"zip_code\": \"60601\"\n },\n \"shipment_id\": 98765,\n \"shipping_service\": \"UPS Ground\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift default import Foundation let headers = [ "shipbob_channel_id": "1", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "origin_address": [ "city": "Chicago", "company": "ACME Corp", "country": "US", "email": "jane@example.com", "name": "Jane Doe", "phone": "312-555-0100", "state": "IL", "street1": "123 Main St", "street2": "Apt 4B", "zip_code": "60601" ], "shipment_id": 98765, "shipping_service": "UPS Ground" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox-api.shipbob.com/Experimental/return/1/label?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() ```