Create Label
curl --request POST \
--url https://api.loopreturns.com/api/2026-10/labels \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"label_request_id": 67329889100573,
"tracking_number": "9400136105440512280610",
"carrier": "usps",
"label_url": "https://s3.amazonaws.com/example-bucket/label.pdf",
"rate": [
{
"amount": 50000,
"currency_code": "USD"
},
{
"amount": 25000,
"currency_code": "CAD"
},
{
"amount": 1500,
"currency_code": "EUR"
}
],
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610",
"qrcode_url": "https://s3.amazonaws.com/example-bucket/qrcode.pdf"
}
'import requests
url = "https://api.loopreturns.com/api/2026-10/labels"
payload = {
"label_request_id": 67329889100573,
"tracking_number": "9400136105440512280610",
"carrier": "usps",
"label_url": "https://s3.amazonaws.com/example-bucket/label.pdf",
"rate": [
{
"amount": 50000,
"currency_code": "USD"
},
{
"amount": 25000,
"currency_code": "CAD"
},
{
"amount": 1500,
"currency_code": "EUR"
}
],
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610",
"qrcode_url": "https://s3.amazonaws.com/example-bucket/qrcode.pdf"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
label_request_id: 67329889100573,
tracking_number: '9400136105440512280610',
carrier: 'usps',
label_url: 'https://s3.amazonaws.com/example-bucket/label.pdf',
rate: [
{amount: 50000, currency_code: 'USD'},
{amount: 25000, currency_code: 'CAD'},
{amount: 1500, currency_code: 'EUR'}
],
tracking_url: 'https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610',
qrcode_url: 'https://s3.amazonaws.com/example-bucket/qrcode.pdf'
})
};
fetch('https://api.loopreturns.com/api/2026-10/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/2026-10/labels",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'label_request_id' => 67329889100573,
'tracking_number' => '9400136105440512280610',
'carrier' => 'usps',
'label_url' => 'https://s3.amazonaws.com/example-bucket/label.pdf',
'rate' => [
[
'amount' => 50000,
'currency_code' => 'USD'
],
[
'amount' => 25000,
'currency_code' => 'CAD'
],
[
'amount' => 1500,
'currency_code' => 'EUR'
]
],
'tracking_url' => 'https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610',
'qrcode_url' => 'https://s3.amazonaws.com/example-bucket/qrcode.pdf'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.loopreturns.com/api/2026-10/labels"
payload := strings.NewReader("{\n \"label_request_id\": 67329889100573,\n \"tracking_number\": \"9400136105440512280610\",\n \"carrier\": \"usps\",\n \"label_url\": \"https://s3.amazonaws.com/example-bucket/label.pdf\",\n \"rate\": [\n {\n \"amount\": 50000,\n \"currency_code\": \"USD\"\n },\n {\n \"amount\": 25000,\n \"currency_code\": \"CAD\"\n },\n {\n \"amount\": 1500,\n \"currency_code\": \"EUR\"\n }\n ],\n \"tracking_url\": \"https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610\",\n \"qrcode_url\": \"https://s3.amazonaws.com/example-bucket/qrcode.pdf\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.loopreturns.com/api/2026-10/labels")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"label_request_id\": 67329889100573,\n \"tracking_number\": \"9400136105440512280610\",\n \"carrier\": \"usps\",\n \"label_url\": \"https://s3.amazonaws.com/example-bucket/label.pdf\",\n \"rate\": [\n {\n \"amount\": 50000,\n \"currency_code\": \"USD\"\n },\n {\n \"amount\": 25000,\n \"currency_code\": \"CAD\"\n },\n {\n \"amount\": 1500,\n \"currency_code\": \"EUR\"\n }\n ],\n \"tracking_url\": \"https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610\",\n \"qrcode_url\": \"https://s3.amazonaws.com/example-bucket/qrcode.pdf\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.loopreturns.com/api/2026-10/labels")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"label_request_id\": 67329889100573,\n \"tracking_number\": \"9400136105440512280610\",\n \"carrier\": \"usps\",\n \"label_url\": \"https://s3.amazonaws.com/example-bucket/label.pdf\",\n \"rate\": [\n {\n \"amount\": 50000,\n \"currency_code\": \"USD\"\n },\n {\n \"amount\": 25000,\n \"currency_code\": \"CAD\"\n },\n {\n \"amount\": 1500,\n \"currency_code\": \"EUR\"\n }\n ],\n \"tracking_url\": \"https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610\",\n \"qrcode_url\": \"https://s3.amazonaws.com/example-bucket/qrcode.pdf\"\n}"
response = http.request(request)
puts response.read_body{
"id": 67329889100573,
"tracking_number": "9400136105440512280610",
"carrier": "usps",
"rate": [
{
"amount": 50000,
"currency_code": "USD"
},
{
"amount": 25000,
"currency_code": "CAD"
},
{
"amount": 1500,
"currency_code": "EUR"
}
],
"status": "new",
"created_at": "2023-04-25T13:25:00-05:00",
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610",
"label_url": "https://s3.amazonaws.com/example-bucket/label.pdf",
"qrcode_url": "https://s3.amazonaws.com/example-bucket/qrcode.pdf"
}{
"errors": "Unauthorized."
}{
"errors": "Label request not found."
}{
"message": "The status field is required.",
"errors": {
"status": [
"The status field is required."
]
}
}{
"errors": "Error posting label create request."
}Label Requests
Create Label
Create a label for a label request.
This endpoint may legitimately be called for a label request that previously
reported one or more errors via POST /label-requests/{id}/errors — that is how a
transient failure is recovered. On success it moves the label request’s status to
fulfilled. The id returned in this endpoint’s response identifies the created
label, not the label request — it is that label id, not the label request id, that
PUT /labels/{id} takes.
Required API key scopes
- Labels (Write)
POST
/
labels
Create Label
curl --request POST \
--url https://api.loopreturns.com/api/2026-10/labels \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"label_request_id": 67329889100573,
"tracking_number": "9400136105440512280610",
"carrier": "usps",
"label_url": "https://s3.amazonaws.com/example-bucket/label.pdf",
"rate": [
{
"amount": 50000,
"currency_code": "USD"
},
{
"amount": 25000,
"currency_code": "CAD"
},
{
"amount": 1500,
"currency_code": "EUR"
}
],
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610",
"qrcode_url": "https://s3.amazonaws.com/example-bucket/qrcode.pdf"
}
'import requests
url = "https://api.loopreturns.com/api/2026-10/labels"
payload = {
"label_request_id": 67329889100573,
"tracking_number": "9400136105440512280610",
"carrier": "usps",
"label_url": "https://s3.amazonaws.com/example-bucket/label.pdf",
"rate": [
{
"amount": 50000,
"currency_code": "USD"
},
{
"amount": 25000,
"currency_code": "CAD"
},
{
"amount": 1500,
"currency_code": "EUR"
}
],
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610",
"qrcode_url": "https://s3.amazonaws.com/example-bucket/qrcode.pdf"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
label_request_id: 67329889100573,
tracking_number: '9400136105440512280610',
carrier: 'usps',
label_url: 'https://s3.amazonaws.com/example-bucket/label.pdf',
rate: [
{amount: 50000, currency_code: 'USD'},
{amount: 25000, currency_code: 'CAD'},
{amount: 1500, currency_code: 'EUR'}
],
tracking_url: 'https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610',
qrcode_url: 'https://s3.amazonaws.com/example-bucket/qrcode.pdf'
})
};
fetch('https://api.loopreturns.com/api/2026-10/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/2026-10/labels",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'label_request_id' => 67329889100573,
'tracking_number' => '9400136105440512280610',
'carrier' => 'usps',
'label_url' => 'https://s3.amazonaws.com/example-bucket/label.pdf',
'rate' => [
[
'amount' => 50000,
'currency_code' => 'USD'
],
[
'amount' => 25000,
'currency_code' => 'CAD'
],
[
'amount' => 1500,
'currency_code' => 'EUR'
]
],
'tracking_url' => 'https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610',
'qrcode_url' => 'https://s3.amazonaws.com/example-bucket/qrcode.pdf'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.loopreturns.com/api/2026-10/labels"
payload := strings.NewReader("{\n \"label_request_id\": 67329889100573,\n \"tracking_number\": \"9400136105440512280610\",\n \"carrier\": \"usps\",\n \"label_url\": \"https://s3.amazonaws.com/example-bucket/label.pdf\",\n \"rate\": [\n {\n \"amount\": 50000,\n \"currency_code\": \"USD\"\n },\n {\n \"amount\": 25000,\n \"currency_code\": \"CAD\"\n },\n {\n \"amount\": 1500,\n \"currency_code\": \"EUR\"\n }\n ],\n \"tracking_url\": \"https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610\",\n \"qrcode_url\": \"https://s3.amazonaws.com/example-bucket/qrcode.pdf\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.loopreturns.com/api/2026-10/labels")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"label_request_id\": 67329889100573,\n \"tracking_number\": \"9400136105440512280610\",\n \"carrier\": \"usps\",\n \"label_url\": \"https://s3.amazonaws.com/example-bucket/label.pdf\",\n \"rate\": [\n {\n \"amount\": 50000,\n \"currency_code\": \"USD\"\n },\n {\n \"amount\": 25000,\n \"currency_code\": \"CAD\"\n },\n {\n \"amount\": 1500,\n \"currency_code\": \"EUR\"\n }\n ],\n \"tracking_url\": \"https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610\",\n \"qrcode_url\": \"https://s3.amazonaws.com/example-bucket/qrcode.pdf\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.loopreturns.com/api/2026-10/labels")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"label_request_id\": 67329889100573,\n \"tracking_number\": \"9400136105440512280610\",\n \"carrier\": \"usps\",\n \"label_url\": \"https://s3.amazonaws.com/example-bucket/label.pdf\",\n \"rate\": [\n {\n \"amount\": 50000,\n \"currency_code\": \"USD\"\n },\n {\n \"amount\": 25000,\n \"currency_code\": \"CAD\"\n },\n {\n \"amount\": 1500,\n \"currency_code\": \"EUR\"\n }\n ],\n \"tracking_url\": \"https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610\",\n \"qrcode_url\": \"https://s3.amazonaws.com/example-bucket/qrcode.pdf\"\n}"
response = http.request(request)
puts response.read_body{
"id": 67329889100573,
"tracking_number": "9400136105440512280610",
"carrier": "usps",
"rate": [
{
"amount": 50000,
"currency_code": "USD"
},
{
"amount": 25000,
"currency_code": "CAD"
},
{
"amount": 1500,
"currency_code": "EUR"
}
],
"status": "new",
"created_at": "2023-04-25T13:25:00-05:00",
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610",
"label_url": "https://s3.amazonaws.com/example-bucket/label.pdf",
"qrcode_url": "https://s3.amazonaws.com/example-bucket/qrcode.pdf"
}{
"errors": "Unauthorized."
}{
"errors": "Label request not found."
}{
"message": "The status field is required.",
"errors": {
"status": [
"The status field is required."
]
}
}{
"errors": "Error posting label create request."
}Authorizations
oauth2labels-write
The access token received from the authorization server in the OAuth 2.0 flow.
Body
application/json
- Option 1
- Option 2
The label request id this label applies to.
Example:
67329889100573
The tracking number associated with the label.
Maximum string length:
256Example:
"9400136105440512280610"
The carrier's standard name in lowercase (for example usps, fedex, ups) — never
the tracking number or an internal reference. Loop uses this together with
tracking_number to track the shipment automatically, for supported carriers; an
incorrect value means automatic tracking never starts.
Maximum string length:
32Example:
"usps"
The URL containing the printable PDF of the labels.
Required unless qrcode_url is provided.
Maximum string length:
2048Example:
"https://s3.amazonaws.com/example-bucket/label.pdf"
Show child attributes
Show child attributes
Example:
[
{ "amount": 50000, "currency_code": "USD" },
{ "amount": 25000, "currency_code": "CAD" },
{ "amount": 1500, "currency_code": "EUR" }
]
The tracking URL associated with the label. Strongly recommended — it gives the
shopper a working tracking link right away, even before Loop's automatic status
tracking (see carrier) produces an update.
Maximum string length:
2048Example:
"https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610"
The QR Code URL containing the printable PDF of the labels.
Maximum string length:
512Example:
"https://s3.amazonaws.com/example-bucket/qrcode.pdf"
Response
Created
The id of the label you created.
Example:
67329889100573
The tracking number associated with the label.
Example:
"9400136105440512280610"
The carrier associated with the label.
Example:
"usps"
Show child attributes
Show child attributes
Example:
[
{ "amount": 50000, "currency_code": "USD" },
{ "amount": 25000, "currency_code": "CAD" },
{ "amount": 1500, "currency_code": "EUR" }
]
The current status of the label.
Available options:
queueable, queued, queued_for_purchase, purchase_failed, new, pre_transit, in_transit, out_for_delivery, delivered, available_for_pickup, cancelled, unknown, return_to_sender, failure, error, refund_requested Example:
"new"
A date-time value in ISO 8601 format. What it represents (for example, when a label, label request, or reported error was created, or a date-range filter bound) depends on the field or parameter referencing this schema.
Example:
"2023-04-25T13:25:00-05:00"
The tracking URL associated with the label.
Example:
"https://tools.usps.com/go/TrackConfirmAction_input?strOrigTrackNum=9400136105440512280610"
The URL containing the printable PDF of the labels.
Example:
"https://s3.amazonaws.com/example-bucket/label.pdf"
The QR Code URL containing the printable PDF of the labels.
Example:
"https://s3.amazonaws.com/example-bucket/qrcode.pdf"