Create Return Label

POST

/create-return-label

Buys a return label for an existing outbound shipment. The addresses and items are taken from the
original shipment, so they are not sent again. Across a customs border the invoice is filed as
returned goods. A shipment can have one live return label at a time; void it with
POST /v1/void-label to buy another.

Business errors are answered with HTTP 200 and success: false:
SHIPMENT_ID_REQUIRED, SHIPMENT_NOT_FOUND (missing or voided), SHIPMENT_IS_RETURN,
RETURN_LABEL_EXISTS, ALREADY_CREATING_RETURN_LABEL, RETURN_ADDRESS_NOT_FOUND.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Success

Bodyapplication/json

🟠401

🟠426

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.byelabel.com/v1/create-return-label' \
--header 'X-Workspace-Id: ' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "shipment_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "carrier": {
        "code": "ups",
        "service": "03",
        "packaging": "02"
    },
    "date": "2026-10-30"
}'

Response Example

200 - Return label bought

{
    "success": true,
    "payload": {
        "id": "0b6c1f0e-3a3e-4c55-9d2e-8f6b2f7a1c11",
        "is_return": true,
        "return_of_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "status": "pre_transit",
        "tracking_number": "1Z999AA10123456784",
        "carrier": {
            "code": "ups",
            "name": "UPS",
            "service": {
                "code": "03",
                "name": "UPS Ground"
            },
            "packaging": {
                "code": "02",
                "name": "Package"
            }
        },
        "currency": "USD",
        "cost": 12.45,
        "tax": 0,
        "total_cost": 12.45,
        "label": {
            "format": "pdf",
            "data": "JVBERi0xLjQK..."
        },
        "created_at": "2026-10-30T09:12:44.000Z"
    },
    "transaction": {
        "id": "5d41402abc4b2a76b9719d911017c592",
        "response_time": 2843.12
    }
}

Modified at 2026-10-30 09:52:16

Create Shipment (Label)

Void Shipment (Label)