# Add Label API

Production endpoint URL:

```
https://returns-api.parcellab.com/prod/addLabelById
```

For details on access, view the overview here:

{% content-ref url="" %}
[](https://docs.parcellab.com/docs/developers/v2/returns/rma-actions-api)
{% endcontent-ref %}

### What This Endpoint Achieves

When successful, the API:

* Creates or registers one additional label for the return
* Appends label data to `returnLabelsAdditional`
* Creates/updates tracking records for the new label

Common use cases:

* Customer needs one more parcel label
* Customer support manually adds an external label/tracking number

### Request

#### Headers

<table><thead><tr><th width="181">Header</th><th width="129">Required</th><th>Type</th></tr></thead><tbody><tr><td><code>user</code></td><td>yes</td><td>string</td></tr><tr><td><code>Content-Type</code></td><td>yes</td><td>string (<code>application/json</code>)</td></tr></tbody></table>

#### JSON Body

<table><thead><tr><th width="276.5">Field</th><th width="118.5">Required</th><th width="136">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>returnId</code></td><td>yes</td><td>string</td><td>24-character return ID.</td></tr><tr><td><code>lang</code></td><td>yes</td><td>string</td><td>Language context.</td></tr><tr><td><code>country</code></td><td>yes</td><td>string</td><td>Country/market context.</td></tr><tr><td><code>draft</code></td><td>no</td><td>string</td><td>Set to <code>true</code> for draft config.</td></tr><tr><td><code>weightInGrams</code></td><td>no</td><td>integer</td><td>Optional weight hint for label generation.</td></tr><tr><td><code>requestedByCustomerService</code></td><td>no</td><td>boolean</td><td>Customer service override for additional-label restrictions.</td></tr><tr><td><code>courier</code></td><td>no</td><td>string</td><td>Courier code/name for manual label registration.</td></tr><tr><td><code>trackingNumber</code></td><td>no</td><td>string</td><td>Tracking number for manual label registration.</td></tr></tbody></table>

#### Manual label mode

If you want to register a label manually (without label generation), send both:

* `courier`
* `trackingNumber`

### Example Request (generated label)

```bash
curl \
  -X POST "https://returns-api.parcellab.com/prod/addLabelById" \
  -H "user: 1612198" \
  -H "Content-Type: application/json" \
  -d '{
    "returnId": "af0000000000000000000001",
    "lang": "en",
    "country": "us",
    "weightInGrams": 1800
  }'
```

### Example Request (manual label)

```bash
curl \
  -X POST "https://returns-api.parcellab.com/prod/addLabelById" \
  -H "user: 1612198" \
  -H "Content-Type: application/json" \
  -d '{
    "returnId": "af0000000000000000000001",
    "lang": "en",
    "country": "us",
    "courier": "ups",
    "trackingNumber": "1Z12345E0205271688"
  }'
```

### Success Response (`200 OK`)

```json
{
  "returnId": "af0000000000000000000001",
  "returnLabelDetails": {
    "courier": "ups",
    "tracking_number": "1Z12345E0205271688",
    "isAdditionalLabel": true
  },
  "canAddLabels": true
}
```

<table><thead><tr><th width="190">Field</th><th width="125">Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>returnId</code></td><td>string</td><td>Return ID affected.</td></tr><tr><td><code>returnLabelDetails</code></td><td>object</td><td>Details of the newly added label.</td></tr><tr><td><code>canAddLabels</code></td><td>boolean</td><td>Whether more additional labels are still allowed after this call.</td></tr></tbody></table>

### Business Rules

* Additional-label permissions may depend on merchant configuration.
* A per-return label limit may apply.
* Pickup couriers may be restricted from additional label generation.

### Error Responses

<table><thead><tr><th width="113.5">Status</th><th>Error value</th><th>Meaning</th></tr></thead><tbody><tr><td><code>400</code></td><td><code>Payload schema validation failed.</code></td><td>Missing/invalid request input.</td></tr><tr><td><code>400</code></td><td><code>User does not have additional labels button.</code></td><td>Merchant config does not allow additional labels.</td></tr><tr><td><code>400</code></td><td><code>Not allowed to add additional label.</code></td><td>Return is not eligible for adding more labels.</td></tr><tr><td><code>400</code></td><td><code>Courier does not offer requested label function.</code></td><td>Selected courier does not support label flow.</td></tr><tr><td><code>400</code></td><td><code>Label generation failed.</code></td><td>Label creation failed.</td></tr><tr><td><code>400</code></td><td><code>No modifiers to update is set</code></td><td>No valid change could be applied.</td></tr><tr><td><code>400</code></td><td><code>Update return failed.</code></td><td>DB update/tracking propagation failed.</td></tr><tr><td><code>403</code></td><td><code>FORBIDDEN</code></td><td><code>returnId</code> is not accessible in caller context.</td></tr><tr><td><code>404</code></td><td><code>User not found.</code></td><td>Merchant context not found.</td></tr><tr><td><code>404</code></td><td><code>Order does not exist.</code></td><td><code>returnId</code> not found.</td></tr><tr><td><code>500</code></td><td>implementation-defined</td><td>Unexpected server error.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.parcellab.com/docs/developers/v2/returns/rma-actions-api/add-label-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.