> For the complete documentation index, see [llms.txt](https://docs.parcellab.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parcellab.com/docs/developers/v2/returns/rma-actions-api/add-label-api.md).

# Add Label API

Use this endpoint to add an additional return label to an already-created return.

Production endpoint URL:

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

For details on access, view the overview here:

{% content-ref url="/pages/ECzngWMawj0hRD9NBSDr" %}
[RMA Actions API](/docs/developers/v2/returns/rma-actions-api.md)
{% 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.