curl --request POST \
--url https://api.returnshelper.com/uat/user/api/Label/CancelLabel \
--header 'Content-Type: application/json' \
--header 'x-rr-apikey: <api-key>' \
--header 'x-rr-apitoken: <api-key>' \
--data '{
"labelId": 123
}'import requests
url = "https://api.returnshelper.com/uat/user/api/Label/CancelLabel"
payload = { "labelId": 123 }
headers = {
"x-rr-apikey": "<api-key>",
"x-rr-apitoken": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-rr-apikey': '<api-key>',
'x-rr-apitoken': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({labelId: 123})
};
fetch('https://api.returnshelper.com/uat/user/api/Label/CancelLabel', 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.returnshelper.com/uat/user/api/Label/CancelLabel",
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([
'labelId' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-rr-apikey: <api-key>",
"x-rr-apitoken: <api-key>"
],
]);
$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.returnshelper.com/uat/user/api/Label/CancelLabel"
payload := strings.NewReader("{\n \"labelId\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-rr-apikey", "<api-key>")
req.Header.Add("x-rr-apitoken", "<api-key>")
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.returnshelper.com/uat/user/api/Label/CancelLabel")
.header("x-rr-apikey", "<api-key>")
.header("x-rr-apitoken", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"labelId\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.returnshelper.com/uat/user/api/Label/CancelLabel")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-rr-apikey"] = '<api-key>'
request["x-rr-apitoken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"labelId\": 123\n}"
response = http.request(request)
puts response.read_body{
"correlationId": "<string>",
"meta": {
"status": 123,
"data": {},
"errorCode": "<string>",
"error": {}
}
}{
"correlationId": "<string>",
"meta": {
"status": 123,
"data": {},
"errorCode": "<string>",
"error": {}
}
}Cancel return label
curl --request POST \
--url https://api.returnshelper.com/uat/user/api/Label/CancelLabel \
--header 'Content-Type: application/json' \
--header 'x-rr-apikey: <api-key>' \
--header 'x-rr-apitoken: <api-key>' \
--data '{
"labelId": 123
}'import requests
url = "https://api.returnshelper.com/uat/user/api/Label/CancelLabel"
payload = { "labelId": 123 }
headers = {
"x-rr-apikey": "<api-key>",
"x-rr-apitoken": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-rr-apikey': '<api-key>',
'x-rr-apitoken': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({labelId: 123})
};
fetch('https://api.returnshelper.com/uat/user/api/Label/CancelLabel', 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.returnshelper.com/uat/user/api/Label/CancelLabel",
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([
'labelId' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-rr-apikey: <api-key>",
"x-rr-apitoken: <api-key>"
],
]);
$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.returnshelper.com/uat/user/api/Label/CancelLabel"
payload := strings.NewReader("{\n \"labelId\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-rr-apikey", "<api-key>")
req.Header.Add("x-rr-apitoken", "<api-key>")
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.returnshelper.com/uat/user/api/Label/CancelLabel")
.header("x-rr-apikey", "<api-key>")
.header("x-rr-apitoken", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"labelId\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.returnshelper.com/uat/user/api/Label/CancelLabel")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-rr-apikey"] = '<api-key>'
request["x-rr-apitoken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"labelId\": 123\n}"
response = http.request(request)
puts response.read_body{
"correlationId": "<string>",
"meta": {
"status": 123,
"data": {},
"errorCode": "<string>",
"error": {}
}
}{
"correlationId": "<string>",
"meta": {
"status": 123,
"data": {},
"errorCode": "<string>",
"error": {}
}
}labelId from the create response or from the labelGenerated webhook.
When a label can be cancelled
Every condition below must hold. If one fails, the call returns a validation soft error — HTTP 200 withmeta.status: 400 and meta.errorCode: VALIDATION_FAILED — with the message in meta.error.labelId. See Error codes.
| Condition | meta.error.labelId when it fails |
|---|---|
| The label belongs to your account | Label:{labelId} not found |
The label was generated (labelRequestStatusCode is success) | Cancel label only when label status is success |
The current time is before the label’s cancelCutoffTime | The cancellation cutoff Time {cancelCutoffTime} has already passed. |
| The warehouse has not received the parcel | Cancel label only when shipment status is lb-printed |
cancelCutoffTime is delivered with the label in the labelGenerated webhook and returned by Get return shipment details.
After a successful cancel
Get return shipment details returns:| Field | Value |
|---|---|
returnStatusCode | label-canceled |
shipments[].shipmentStatusCode | lb-canceled |
shipments[].labelId | 0 |
shipments[].label | null |
labelId on your side if you need it later.
Correcting a shipment
A cancelled return request cannot get a new label. To correct a shipment, cancel its label, then call Create return shipment again with the corrected details. The new call returns a newreturnRequestId, shipmentId, and labelId. The cancelled return request stays at label-canceled.
Idempotency
Thex-returnhelper-idempotency-key header is optional. A call without it runs normally, with no protection against duplicates. See Idempotency.
Related
- Create return shipment — create the replacement shipment.
- Get return shipment details — read
cancelCutoffTimeand the current status. - Webhooks —
labelGeneratedcarrieslabelIdandcancelCutoffTime.
Authorizations
Your API key
Your API token — keep this private
Body
ID of the label to cancel, as returned by Create return shipment and the labelGenerated webhook
Response
Success — returns the standard response envelope with no additional payload fields. Inspect meta.status to confirm the label was cancelled.
Universal response envelope. Successful responses include the business payload as additional top-level fields alongside correlationId and meta. Failed responses (auth errors, validation errors) only populate correlationId and meta, with meta.errorCode and meta.error describing the failure.
Unique correlation ID for tracing the request through Return Helper systems.
Application-level metadata for every API response. Inspect status and errorCode to detect soft-error responses (validation failures arrive as HTTP 200 with meta.status: 400).
Show child attributes
Show child attributes