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:

RMA Actions API

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

Header	Required	Type
user	yes	string
Content-Type	yes	string (application/json)

JSON Body

Field	Required	Type	Description
returnId	yes	string	24-character return ID.
lang	yes	string	Language context.
country	yes	string	Country/market context.
draft	no	string	Set to true for draft config.
weightInGrams	no	integer	Optional weight hint for label generation.
requestedByCustomerService	no	boolean	Customer service override for additional-label restrictions.
courier	no	string	Courier code/name for manual label registration.
trackingNumber	no	string	Tracking number for manual label registration.

Manual label mode

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

• courier

• trackingNumber

Example Request (generated label)

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)

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)

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

Field	Type	Meaning
returnId	string	Return ID affected.
returnLabelDetails	object	Details of the newly added label.
canAddLabels	boolean	Whether more additional labels are still allowed after this call.

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

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