Generate Label

curl --request POST \
  --url https://api.loopreturns.com/api/v1/returns/{returnId}/labels \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.loopreturns.com/api/v1/returns/{returnId}/labels"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.loopreturns.com/api/v1/returns/{returnId}/labels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.loopreturns.com/api/v1/returns/{returnId}/labels",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.loopreturns.com/api/v1/returns/{returnId}/labels"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.loopreturns.com/api/v1/returns/{returnId}/labels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "message": "Label generation queued",
  "returnId": 12345
}

{
  "errors": "Unauthorized."
}

{
  "code": "return_not_found",
  "errors": [
    "Return not found."
  ]
}

{
  "code": "label_already_exists",
  "errors": [
    "Label already exists for return [12345]."
  ]
}

{
  "code": "return_cannot_receive_label",
  "errors": [
    "The return is not in a valid state to receive a label."
  ]
}

{
  "code": "internal_error",
  "errors": [
    "Error processing label request."
  ]
}

Label Requests

Generate Label

Queue label generation for a return. This endpoint triggers an asynchronous label generation process for the specified return.

Required API key scope

Returns

Retrieving the Generated Label

After the label generation is queued (202 response), the label will be processed asynchronously. Once generation is complete, you can retrieve the label data by calling the Get Return Details endpoint:

GET /warehouse/return/details?return_id={returnId}

The response will include a labels array containing the generated label with:

url: The link to the shipping label PDF
tracking_number: The tracking number for the shipment
carrier: The shipping carrier (e.g., USPS, UPS)
status: The current status of the label
rate: The shipping cost

Successful Response

Returns HTTP 202 (Accepted) when the label generation has been successfully queued.

Error Responses

404 Not Found (return_not_found): The specified return does not exist
409 Conflict (label_already_exists): A label has already been generated for this return
422 Unprocessable Entity (return_cannot_receive_label): The return is not in a valid state to receive a label
422 Unprocessable Entity (label_generation_failed): A previous label generation attempt failed
500 Internal Server Error (internal_error): An unexpected error occurred

POST

returns

{returnId}

labels

Generate Label

curl --request POST \
  --url https://api.loopreturns.com/api/v1/returns/{returnId}/labels \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.loopreturns.com/api/v1/returns/{returnId}/labels"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.loopreturns.com/api/v1/returns/{returnId}/labels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.loopreturns.com/api/v1/returns/{returnId}/labels",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.loopreturns.com/api/v1/returns/{returnId}/labels"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.loopreturns.com/api/v1/returns/{returnId}/labels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "message": "Label generation queued",
  "returnId": 12345
}

{
  "errors": "Unauthorized."
}

{
  "code": "return_not_found",
  "errors": [
    "Return not found."
  ]
}

{
  "code": "label_already_exists",
  "errors": [
    "Label already exists for return [12345]."
  ]
}

{
  "code": "return_cannot_receive_label",
  "errors": [
    "The return is not in a valid state to receive a label."
  ]
}

{
  "code": "internal_error",
  "errors": [
    "Error processing label request."
  ]
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

returnId

integer

required

The unique identifier for the return, created by Loop.

Example:

12345

Response

Label generation queued successfully

message

string

required

Confirmation message that label generation has been queued.

Example:

"Label generation queued"

returnId

integer<int64>

required

The return ID for which label generation was queued.

Example:

12345

Using the API

APIs

Generate Label

Required API key scope

Retrieving the Generated Label

Successful Response

Error Responses

Authorizations

Path Parameters

Response