Return Registrations
Our API allows you to create, update, and retrieve customer return registrations.
Overview
These requests allow you to generate and modify return registrations with a single HTTPS request.
You can retrieve return registrations associated with your account and a specific return request using its unique ID through these APIs. Additionally, you can retrieve article information for return items as well as generate return labels.
Get Return Registrations
You can retrieve a list of return registrations for your account using the v4/returns/return-registrations endpoint.
Return Registrations represent a return request from a customer. There might be multiple return registrations for a single order. There might also be multiple labels for one return registration, if requested by the customer.
A return registration is linked to a configuration bundle (field 'code'), multiple configurations might be available on one account (e.g. country-specific courier configurations).
Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.
Certain fields of the return registration are not mutable via requests on the registration resource, but require 'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.
Authorizations
Query parameters
accountinteger[]Optional
created_atstring · date-timeOptional
cursorstringOptional
The pagination cursor value.
external_idstring · uuidOptional
external_referencestringOptional
orderingstringOptional
Which field to use when ordering the results.
referencestringOptional
updated_atstring · date-timeOptional
Responses
200Success
application/json
400Error
application/json
403Error
application/json
404Error
application/json
get
GET /v4/returns/return-registrations/ HTTP/1.1
Host:
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"next": "http://api.example.org/accounts/?cursor=cD00ODY%3D\"",
"previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
"results": [
{
"account": 1,
"code": "text",
"version": null,
"client_key": "text",
"reference": "text",
"external_id": "123e4567-e89b-12d3-a456-426614174000",
"external_reference": "text",
"status": "created",
"status_reason": "text",
"original_courier": "text",
"original_order_id": null,
"order_date": null,
"order_currency": "text",
"order_total_amount": null,
"order_delivery_date": null,
"order_shipping_date": null,
"order_payment_method": [
"text"
],
"language_iso2": "text",
"customer_email": "[email protected]",
"customer_phone": "text",
"customer_salutation": "text",
"customer_first_name": "text",
"customer_last_name": "text",
"customer_country_iso3": "text",
"customer_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"articles_order": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"articles_return": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"return_reason": "text",
"return_reason_pretty": "text",
"return_quantity": 1,
"problem_description": "text",
"condition": "text",
"article_images": [
{
"url": "text",
"name": "text",
"mime_type": "text"
}
],
"compensation_method": "text",
"accepted_quantity": 1,
"rejected_quantity": 1,
"status_reason": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"return_labels": [
{
"courier": "text",
"service_level": "text",
"tracking_number": "text",
"type": "shipping",
"flags": [
"is_cancellable"
],
"documents": [
{
"url": "text",
"content_type": "application/pdf",
"type": [
"label"
],
"expires_at": "2025-10-11T19:34:53.524Z"
}
],
"destination_id": "text",
"line_item_ids": [
"text"
],
"is_free_label": false,
"label_cost_amount": "0.0",
"tracking_id": "text",
"external_reference": "text",
"delivery_status": "Pending",
"pickup_date": "2025-10-11",
"pickup_time": "19:34:53",
"is_pickup": false
}
],
"refund_method": "text",
"tags": [
"text"
],
"additional_fields": {},
"verification_code_used": "text",
"created_at": "2025-10-11T19:34:53.524Z",
"updated_at": "2025-10-11T19:34:53.524Z",
"mutations": [
{
"operation_id": "123e4567-e89b-12d3-a456-426614174000",
"result": {
"success": false,
"message": "",
"errors": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"type": "add_label",
"request": {
"type": "shipping",
"courier": "text",
"tracking_number": "text",
"service_level": "text",
"destination_id": "text",
"destination_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"template_id": "text",
"flags": [
"has_dangerous_goods"
],
"types": [
"code"
],
"line_item_ids": [
"text"
],
"additional_fields": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}
]
}
]
}Get a Return Registration
You can retrieve a specific return registration using the v4/returns/return-registrations/{external_id} endpoint.
Return Registrations represent a return request from a customer. There might be multiple return registrations for a single order. There might also be multiple labels for one return registration, if requested by the customer.
A return registration is linked to a configuration bundle (field 'code'), multiple configurations might be available on one account (e.g. country-specific courier configurations).
Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.
Certain fields of the return registration are not mutable via requests on the registration resource, but require 'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.
Authorizations
Path parameters
external_idstring · uuidRequired
Unique identifier for this return registration, generated by parcelLab
Responses
200Success
application/json
400Error
application/json
403Error
application/json
404Error
application/json
get
GET /v4/returns/return-registrations/{external_id}/ HTTP/1.1
Host:
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"account": 1,
"code": "text",
"version": null,
"client_key": "text",
"reference": "text",
"external_id": "123e4567-e89b-12d3-a456-426614174000",
"external_reference": "text",
"status": "created",
"status_reason": "text",
"original_courier": "text",
"original_order_id": null,
"order_date": null,
"order_currency": "text",
"order_total_amount": null,
"order_delivery_date": null,
"order_shipping_date": null,
"order_payment_method": [
"text"
],
"language_iso2": "text",
"customer_email": "[email protected]",
"customer_phone": "text",
"customer_salutation": "text",
"customer_first_name": "text",
"customer_last_name": "text",
"customer_country_iso3": "text",
"customer_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"articles_order": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"articles_return": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"return_reason": "text",
"return_reason_pretty": "text",
"return_quantity": 1,
"problem_description": "text",
"condition": "text",
"article_images": [
{
"url": "text",
"name": "text",
"mime_type": "text"
}
],
"compensation_method": "text",
"accepted_quantity": 1,
"rejected_quantity": 1,
"status_reason": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"return_labels": [
{
"courier": "text",
"service_level": "text",
"tracking_number": "text",
"type": "shipping",
"flags": [
"is_cancellable"
],
"documents": [
{
"url": "text",
"content_type": "application/pdf",
"type": [
"label"
],
"expires_at": "2025-10-11T19:34:53.524Z"
}
],
"destination_id": "text",
"line_item_ids": [
"text"
],
"is_free_label": false,
"label_cost_amount": "0.0",
"tracking_id": "text",
"external_reference": "text",
"delivery_status": "Pending",
"pickup_date": "2025-10-11",
"pickup_time": "19:34:53",
"is_pickup": false
}
],
"refund_method": "text",
"tags": [
"text"
],
"additional_fields": {},
"verification_code_used": "text",
"created_at": "2025-10-11T19:34:53.524Z",
"updated_at": "2025-10-11T19:34:53.524Z",
"mutations": [
{
"operation_id": "123e4567-e89b-12d3-a456-426614174000",
"result": {
"success": false,
"message": "",
"errors": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"type": "add_label",
"request": {
"type": "shipping",
"courier": "text",
"tracking_number": "text",
"service_level": "text",
"destination_id": "text",
"destination_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"template_id": "text",
"flags": [
"has_dangerous_goods"
],
"types": [
"code"
],
"line_item_ids": [
"text"
],
"additional_fields": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}
]
}Create a Return Registration
You can generate a new return registration for your account using the v4/returns/return-registrations endpoint.
Create a new return registration
Authorizations
Query parameters
courier_testingbooleanOptionalDefault:
Set to true to use the test environment for carrier integration.
falsedraftbooleanOptionalDefault:
Set to true to preview behavior using unpublished configuration changes (e.g., article rules or courier options).
falseBody
Represents a return registration
accountintegerRequired
Account, that is linked to this registration.
codestring · min: 1 · max: 255Required
Configuration code of the return configuration
versionstring | nullOptional
referencestring · min: 1 · max: 255Required
Retailer reference, e.g. the order number, not unique
external_idstring · uuidOptional
Unique identifier for this return registration, generated by parcelLab
external_referencestring · max: 255Optional
Additional identifier (e.g. shop system id) for this return registration, generated by the retailer
statusall ofOptional
If true, the registration has been submitted. This is a read-only field.
created- Createdsubmitted- Submittedpending_approval- Pending Approvalapproved- Approvedrejected- Rejectedcancelled- Cancelledclosed- Closedprocessing_failed- Processing Failed
string · enumOptionalPossible values:
created- Createdsubmitted- Submittedpending_approval- Pending Approvalapproved- Approvedrejected- Rejectedcancelled- Cancelledclosed- Closedprocessing_failed- Processing Failed
status_reasonstring · max: 255Optional
Reason for the current status
original_courierstring · max: 255Optional
original_order_idstring | null · max: 255Optional
order_datestring | nullOptional
Date of the order
order_currencystring · max: 3Optional
Currency of the order, e.g. USD, EUR (ISO 4217)
order_total_amountstring | nullOptionalPattern:
Total amount of the original order
^-?\d{0,8}(?:\.\d{0,2})?$order_delivery_datestring | nullOptional
Date of the order delivery
order_shipping_datestring | nullOptional
Date of the order shipment
order_payment_methodstring[]Optional
Payment method used for the order, as setup as reference items in the accounts configuration
language_iso2string · max: 3Optional
ISO 639-1 language code of the recipient, if known, required for localized communication
customer_emailany of · min: 1Required
Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.
string · emailOptional
const: _unsetOptionalPossible values:
customer_phonestring · max: 255Optional
Customer phone number
customer_salutationstring · max: 255Optional
customer_first_namestring · max: 255Optional
customer_last_namestring · max: 255Optional
customer_country_iso3string · max: 3Optional
ISO 3166-1 alpha-3 code of country
refund_methodstring · max: 255Optional
Refund method selected by customer
tagsstring[]Optional
Tags for the object, format :e.g. 'category:Home Apparel'
additional_fieldsobjectOptional
Additional fields for the return registration
verification_code_usedstring · max: 255Optional
Verification code (e.g. zip/email) used for this return registration
Responses
201Success
application/json
400Error
application/json
403Error
application/json
404Error
application/json
post
POST /v4/returns/return-registrations/ HTTP/1.1
Host:
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 486
{
"account": 161912,
"code": "de-de",
"reference": "O-123123",
"external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
"original_courier": "dhl-germany",
"order_date": "2019-08-24T14:15:22Z",
"order_currency": "EUR",
"order_total_amount": "12.12",
"order_payment_method": [
"gift-card"
],
"customer_email": "[email protected]",
"customer_salutation": "mr",
"customer_first_name": "Foo",
"customer_last_name": "Bar",
"customer_country_iso3": "DEU",
"mutations": [
{
"type": "add_label",
"request": {
"courier": "dhl-germany"
}
}
]
}{
"account": 161912,
"code": "de-de",
"reference": "O-123123",
"external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
"original_courier": "dhl-germany",
"order_date": "2019-08-24T14:15:22Z",
"order_currency": "EUR",
"order_total_amount": "12.12",
"order_payment_method": [
"gift-card"
],
"customer_email": "[email protected]",
"customer_salutation": "mr",
"customer_first_name": "Foo",
"customer_last_name": "Bar",
"customer_country_iso3": "DEU"
}Create a Return Registration via Order Information
You can generate a new return registration for your account from the order details using the v4/returns/return-registrations/lookup-order endpoint.
Return Registrations represent a return request from a customer. There might be multiple return registrations for a single order. There might also be multiple labels for one return registration, if requested by the customer.
A return registration is linked to a configuration bundle (field 'code'), multiple configurations might be available on one account (e.g. country-specific courier configurations).
Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.
Certain fields of the return registration are not mutable via requests on the registration resource, but require 'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.
Authorizations
Body
accountintegerRequired
The account ID to create this return registration on.
codestringRequired
Configuration code (unique identifier of the return portal or configuration used for this return
Responses
200Success
application/json
400Error
application/json
404Error
application/json
429Error
application/json
post
POST /v4/returns/return-registrations/lookup-order/ HTTP/1.1
Host:
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 81
{
"account": 1,
"code": "text",
"identifier": {
"reference": "text",
"identifier": "text"
}
}{
"account": 1,
"code": "text",
"version": null,
"client_key": "text",
"reference": "text",
"external_id": "123e4567-e89b-12d3-a456-426614174000",
"external_reference": "text",
"status": "created",
"status_reason": "text",
"original_courier": "text",
"original_order_id": null,
"order_date": null,
"order_currency": "text",
"order_total_amount": null,
"order_delivery_date": null,
"order_shipping_date": null,
"order_payment_method": [
"text"
],
"language_iso2": "text",
"customer_email": "[email protected]",
"customer_phone": "text",
"customer_salutation": "text",
"customer_first_name": "text",
"customer_last_name": "text",
"customer_country_iso3": "text",
"customer_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"articles_order": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"articles_return": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"return_reason": "text",
"return_reason_pretty": "text",
"return_quantity": 1,
"problem_description": "text",
"condition": "text",
"article_images": [
{
"url": "text",
"name": "text",
"mime_type": "text"
}
],
"compensation_method": "text",
"accepted_quantity": 1,
"rejected_quantity": 1,
"status_reason": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"return_labels": [
{
"courier": "text",
"service_level": "text",
"tracking_number": "text",
"type": "shipping",
"flags": [
"is_cancellable"
],
"documents": [
{
"url": "text",
"content_type": "application/pdf",
"type": [
"label"
],
"expires_at": "2025-10-11T19:34:53.524Z"
}
],
"destination_id": "text",
"line_item_ids": [
"text"
],
"is_free_label": false,
"label_cost_amount": "0.0",
"tracking_id": "text",
"external_reference": "text",
"delivery_status": "Pending",
"pickup_date": "2025-10-11",
"pickup_time": "19:34:53",
"is_pickup": false
}
],
"refund_method": "text",
"tags": [
"text"
],
"additional_fields": {},
"verification_code_used": "text",
"created_at": "2025-10-11T19:34:53.524Z",
"updated_at": "2025-10-11T19:34:53.524Z",
"mutations": [
{
"operation_id": "123e4567-e89b-12d3-a456-426614174000",
"result": {
"success": false,
"message": "",
"errors": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"type": "add_label",
"request": {
"type": "shipping",
"courier": "text",
"tracking_number": "text",
"service_level": "text",
"destination_id": "text",
"destination_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"template_id": "text",
"flags": [
"has_dangerous_goods"
],
"types": [
"code"
],
"line_item_ids": [
"text"
],
"additional_fields": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}
]
}Update a Return Registration
You can update a specific return registration using the v4/returns/return-registrations/{external_id} endpoint.
Return Registrations represent a return request from a customer. There might be multiple return registrations for a single order. There might also be multiple labels for one return registration, if requested by the customer.
A return registration is linked to a configuration bundle (field 'code'), multiple configurations might be available on one account (e.g. country-specific courier configurations).
Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.
Certain fields of the return registration are not mutable via requests on the registration resource, but require 'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.
Authorizations
Path parameters
external_idstring · uuidRequired
Unique identifier for this return registration, generated by parcelLab
Body
Represents a return registration
accountintegerRequired
Account, that is linked to this registration.
codestring · min: 1 · max: 255Required
Configuration code of the return configuration
versionstring | nullOptional
referencestring · min: 1 · max: 255Required
Retailer reference, e.g. the order number, not unique
external_idstring · uuidOptional
Unique identifier for this return registration, generated by parcelLab
external_referencestring · max: 255Optional
Additional identifier (e.g. shop system id) for this return registration, generated by the retailer
statusall ofOptional
If true, the registration has been submitted. This is a read-only field.
created- Createdsubmitted- Submittedpending_approval- Pending Approvalapproved- Approvedrejected- Rejectedcancelled- Cancelledclosed- Closedprocessing_failed- Processing Failed
string · enumOptionalPossible values:
created- Createdsubmitted- Submittedpending_approval- Pending Approvalapproved- Approvedrejected- Rejectedcancelled- Cancelledclosed- Closedprocessing_failed- Processing Failed
status_reasonstring · max: 255Optional
Reason for the current status
original_courierstring · max: 255Optional
original_order_idstring | null · max: 255Optional
order_datestring | nullOptional
Date of the order
order_currencystring · max: 3Optional
Currency of the order, e.g. USD, EUR (ISO 4217)
order_total_amountstring | nullOptionalPattern:
Total amount of the original order
^-?\d{0,8}(?:\.\d{0,2})?$order_delivery_datestring | nullOptional
Date of the order delivery
order_shipping_datestring | nullOptional
Date of the order shipment
order_payment_methodstring[]Optional
Payment method used for the order, as setup as reference items in the accounts configuration
language_iso2string · max: 3Optional
ISO 639-1 language code of the recipient, if known, required for localized communication
customer_emailany of · min: 1Required
Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.
string · emailOptional
const: _unsetOptionalPossible values:
customer_phonestring · max: 255Optional
Customer phone number
customer_salutationstring · max: 255Optional
customer_first_namestring · max: 255Optional
customer_last_namestring · max: 255Optional
customer_country_iso3string · max: 3Optional
ISO 3166-1 alpha-3 code of country
refund_methodstring · max: 255Optional
Refund method selected by customer
tagsstring[]Optional
Tags for the object, format :e.g. 'category:Home Apparel'
additional_fieldsobjectOptional
Additional fields for the return registration
verification_code_usedstring · max: 255Optional
Verification code (e.g. zip/email) used for this return registration
Responses
200Success
application/json
400Error
application/json
403Error
application/json
404Error
application/json
put
PUT /v4/returns/return-registrations/{external_id}/ HTTP/1.1
Host:
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 3132
{
"account": 1,
"code": "text",
"version": null,
"reference": "text",
"external_id": "123e4567-e89b-12d3-a456-426614174000",
"external_reference": "text",
"status": "created",
"status_reason": "text",
"original_courier": "text",
"original_order_id": null,
"order_date": null,
"order_currency": "text",
"order_total_amount": null,
"order_delivery_date": null,
"order_shipping_date": null,
"order_payment_method": [
"text"
],
"language_iso2": "text",
"customer_email": "[email protected]",
"customer_phone": "text",
"customer_salutation": "text",
"customer_first_name": "text",
"customer_last_name": "text",
"customer_country_iso3": "text",
"customer_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"articles_order": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"articles_return": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"return_reason": "text",
"return_reason_pretty": "text",
"return_quantity": 1,
"problem_description": "text",
"condition": "text",
"article_images": [
{
"url": "text",
"name": "text",
"mime_type": "text"
}
],
"compensation_method": "text",
"accepted_quantity": 1,
"rejected_quantity": 1,
"status_reason": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"refund_method": "text",
"tags": [
"text"
],
"additional_fields": {},
"verification_code_used": "text",
"mutations": [
{
"operation_id": "123e4567-e89b-12d3-a456-426614174000",
"result": {
"success": false,
"message": "",
"errors": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"type": "add_label",
"request": {
"type": "shipping",
"courier": "text",
"tracking_number": "text",
"service_level": "text",
"destination_id": "text",
"destination_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"template_id": "text",
"flags": [
"has_dangerous_goods"
],
"types": [
"code"
],
"line_item_ids": [
"text"
],
"additional_fields": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}
]
}{
"account": 1,
"code": "text",
"version": null,
"client_key": "text",
"reference": "text",
"external_id": "123e4567-e89b-12d3-a456-426614174000",
"external_reference": "text",
"status": "created",
"status_reason": "text",
"original_courier": "text",
"original_order_id": null,
"order_date": null,
"order_currency": "text",
"order_total_amount": null,
"order_delivery_date": null,
"order_shipping_date": null,
"order_payment_method": [
"text"
],
"language_iso2": "text",
"customer_email": "[email protected]",
"customer_phone": "text",
"customer_salutation": "text",
"customer_first_name": "text",
"customer_last_name": "text",
"customer_country_iso3": "text",
"customer_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"articles_order": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"articles_return": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"return_reason": "text",
"return_reason_pretty": "text",
"return_quantity": 1,
"problem_description": "text",
"condition": "text",
"article_images": [
{
"url": "text",
"name": "text",
"mime_type": "text"
}
],
"compensation_method": "text",
"accepted_quantity": 1,
"rejected_quantity": 1,
"status_reason": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"return_labels": [
{
"courier": "text",
"service_level": "text",
"tracking_number": "text",
"type": "shipping",
"flags": [
"is_cancellable"
],
"documents": [
{
"url": "text",
"content_type": "application/pdf",
"type": [
"label"
],
"expires_at": "2025-10-11T19:34:53.524Z"
}
],
"destination_id": "text",
"line_item_ids": [
"text"
],
"is_free_label": false,
"label_cost_amount": "0.0",
"tracking_id": "text",
"external_reference": "text",
"delivery_status": "Pending",
"pickup_date": "2025-10-11",
"pickup_time": "19:34:53",
"is_pickup": false
}
],
"refund_method": "text",
"tags": [
"text"
],
"additional_fields": {},
"verification_code_used": "text",
"created_at": "2025-10-11T19:34:53.524Z",
"updated_at": "2025-10-11T19:34:53.524Z",
"mutations": [
{
"operation_id": "123e4567-e89b-12d3-a456-426614174000",
"result": {
"success": false,
"message": "",
"errors": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"type": "add_label",
"request": {
"type": "shipping",
"courier": "text",
"tracking_number": "text",
"service_level": "text",
"destination_id": "text",
"destination_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"template_id": "text",
"flags": [
"has_dangerous_goods"
],
"types": [
"code"
],
"line_item_ids": [
"text"
],
"additional_fields": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}
]
}Partially Update a Return Registration
You can partially update a specific return registration using the v4/returns/return-registrations/{external_id} endpoint.
Return Registrations represent a return request from a customer. There might be multiple return registrations for a single order. There might also be multiple labels for one return registration, if requested by the customer.
A return registration is linked to a configuration bundle (field 'code'), multiple configurations might be available on one account (e.g. country-specific courier configurations).
Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.
Certain fields of the return registration are not mutable via requests on the registration resource, but require 'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.
Authorizations
Path parameters
external_idstring · uuidRequired
Unique identifier for this return registration, generated by parcelLab
Body
Represents a return registration
accountintegerOptional
Account, that is linked to this registration.
codestring · min: 1 · max: 255Optional
Configuration code of the return configuration
versionstring | nullOptional
referencestring · min: 1 · max: 255Optional
Retailer reference, e.g. the order number, not unique
external_idstring · uuidOptional
Unique identifier for this return registration, generated by parcelLab
external_referencestring · max: 255Optional
Additional identifier (e.g. shop system id) for this return registration, generated by the retailer
statusall ofOptional
If true, the registration has been submitted. This is a read-only field.
created- Createdsubmitted- Submittedpending_approval- Pending Approvalapproved- Approvedrejected- Rejectedcancelled- Cancelledclosed- Closedprocessing_failed- Processing Failed
string · enumOptionalPossible values:
created- Createdsubmitted- Submittedpending_approval- Pending Approvalapproved- Approvedrejected- Rejectedcancelled- Cancelledclosed- Closedprocessing_failed- Processing Failed
status_reasonstring · max: 255Optional
Reason for the current status
original_courierstring · max: 255Optional
original_order_idstring | null · max: 255Optional
order_datestring | nullOptional
Date of the order
order_currencystring · max: 3Optional
Currency of the order, e.g. USD, EUR (ISO 4217)
order_total_amountstring | nullOptionalPattern:
Total amount of the original order
^-?\d{0,8}(?:\.\d{0,2})?$order_delivery_datestring | nullOptional
Date of the order delivery
order_shipping_datestring | nullOptional
Date of the order shipment
order_payment_methodstring[]Optional
Payment method used for the order, as setup as reference items in the accounts configuration
language_iso2string · max: 3Optional
ISO 639-1 language code of the recipient, if known, required for localized communication
customer_emailany of · min: 1Optional
Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.
string · emailOptional
const: _unsetOptionalPossible values:
customer_phonestring · max: 255Optional
Customer phone number
customer_salutationstring · max: 255Optional
customer_first_namestring · max: 255Optional
customer_last_namestring · max: 255Optional
customer_country_iso3string · max: 3Optional
ISO 3166-1 alpha-3 code of country
refund_methodstring · max: 255Optional
Refund method selected by customer
tagsstring[]Optional
Tags for the object, format :e.g. 'category:Home Apparel'
additional_fieldsobjectOptional
Additional fields for the return registration
verification_code_usedstring · max: 255Optional
Verification code (e.g. zip/email) used for this return registration
Responses
200Success
application/json
400Error
application/json
403Error
application/json
404Error
application/json
patch
PATCH /v4/returns/return-registrations/{external_id}/ HTTP/1.1
Host:
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 3132
{
"account": 1,
"code": "text",
"version": null,
"reference": "text",
"external_id": "123e4567-e89b-12d3-a456-426614174000",
"external_reference": "text",
"status": "created",
"status_reason": "text",
"original_courier": "text",
"original_order_id": null,
"order_date": null,
"order_currency": "text",
"order_total_amount": null,
"order_delivery_date": null,
"order_shipping_date": null,
"order_payment_method": [
"text"
],
"language_iso2": "text",
"customer_email": "[email protected]",
"customer_phone": "text",
"customer_salutation": "text",
"customer_first_name": "text",
"customer_last_name": "text",
"customer_country_iso3": "text",
"customer_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"articles_order": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"articles_return": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"return_reason": "text",
"return_reason_pretty": "text",
"return_quantity": 1,
"problem_description": "text",
"condition": "text",
"article_images": [
{
"url": "text",
"name": "text",
"mime_type": "text"
}
],
"compensation_method": "text",
"accepted_quantity": 1,
"rejected_quantity": 1,
"status_reason": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"refund_method": "text",
"tags": [
"text"
],
"additional_fields": {},
"verification_code_used": "text",
"mutations": [
{
"operation_id": "123e4567-e89b-12d3-a456-426614174000",
"result": {
"success": false,
"message": "",
"errors": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"type": "add_label",
"request": {
"type": "shipping",
"courier": "text",
"tracking_number": "text",
"service_level": "text",
"destination_id": "text",
"destination_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"template_id": "text",
"flags": [
"has_dangerous_goods"
],
"types": [
"code"
],
"line_item_ids": [
"text"
],
"additional_fields": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}
]
}{
"account": 1,
"code": "text",
"version": null,
"client_key": "text",
"reference": "text",
"external_id": "123e4567-e89b-12d3-a456-426614174000",
"external_reference": "text",
"status": "created",
"status_reason": "text",
"original_courier": "text",
"original_order_id": null,
"order_date": null,
"order_currency": "text",
"order_total_amount": null,
"order_delivery_date": null,
"order_shipping_date": null,
"order_payment_method": [
"text"
],
"language_iso2": "text",
"customer_email": "[email protected]",
"customer_phone": "text",
"customer_salutation": "text",
"customer_first_name": "text",
"customer_last_name": "text",
"customer_country_iso3": "text",
"customer_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"articles_order": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"articles_return": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"return_reason": "text",
"return_reason_pretty": "text",
"return_quantity": 1,
"problem_description": "text",
"condition": "text",
"article_images": [
{
"url": "text",
"name": "text",
"mime_type": "text"
}
],
"compensation_method": "text",
"accepted_quantity": 1,
"rejected_quantity": 1,
"status_reason": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"return_labels": [
{
"courier": "text",
"service_level": "text",
"tracking_number": "text",
"type": "shipping",
"flags": [
"is_cancellable"
],
"documents": [
{
"url": "text",
"content_type": "application/pdf",
"type": [
"label"
],
"expires_at": "2025-10-11T19:34:53.524Z"
}
],
"destination_id": "text",
"line_item_ids": [
"text"
],
"is_free_label": false,
"label_cost_amount": "0.0",
"tracking_id": "text",
"external_reference": "text",
"delivery_status": "Pending",
"pickup_date": "2025-10-11",
"pickup_time": "19:34:53",
"is_pickup": false
}
],
"refund_method": "text",
"tags": [
"text"
],
"additional_fields": {},
"verification_code_used": "text",
"created_at": "2025-10-11T19:34:53.524Z",
"updated_at": "2025-10-11T19:34:53.524Z",
"mutations": [
{
"operation_id": "123e4567-e89b-12d3-a456-426614174000",
"result": {
"success": false,
"message": "",
"errors": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"type": "add_label",
"request": {
"type": "shipping",
"courier": "text",
"tracking_number": "text",
"service_level": "text",
"destination_id": "text",
"destination_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"template_id": "text",
"flags": [
"has_dangerous_goods"
],
"types": [
"code"
],
"line_item_ids": [
"text"
],
"additional_fields": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}
]
}Modify a Return Registration
You can use the available mutations (for example: generate a label) to update a specific return registration using the v4/returns/return-registrations/{external_id}/mutate endpoint.
Mutate this return registration with one of the available mutations
Authorizations
Path parameters
external_idstring · uuidRequired
Unique identifier for this return registration, generated by parcelLab
Body
Update (mutate) a return registration
Responses
200Success
application/json
400Error
application/json
403Error
application/json
404Error
application/json
post
POST /v4/returns/return-registrations/{external_id}/mutate/ HTTP/1.1
Host:
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 675
{
"mutations": [
{
"operation_id": "123e4567-e89b-12d3-a456-426614174000",
"result": {
"success": false,
"message": "",
"errors": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"type": "add_label",
"request": {
"type": "shipping",
"courier": "text",
"tracking_number": "text",
"service_level": "text",
"destination_id": "text",
"destination_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"template_id": "text",
"flags": [
"has_dangerous_goods"
],
"types": [
"code"
],
"line_item_ids": [
"text"
],
"additional_fields": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}
]
}{
"account": 1,
"code": "text",
"version": null,
"client_key": "text",
"reference": "text",
"external_id": "123e4567-e89b-12d3-a456-426614174000",
"external_reference": "text",
"status": "created",
"status_reason": "text",
"original_courier": "text",
"original_order_id": null,
"order_date": null,
"order_currency": "text",
"order_total_amount": null,
"order_delivery_date": null,
"order_shipping_date": null,
"order_payment_method": [
"text"
],
"language_iso2": "text",
"customer_email": "[email protected]",
"customer_phone": "text",
"customer_salutation": "text",
"customer_first_name": "text",
"customer_last_name": "text",
"customer_country_iso3": "text",
"customer_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"articles_order": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"articles_return": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"return_reason": "text",
"return_reason_pretty": "text",
"return_quantity": 1,
"problem_description": "text",
"condition": "text",
"article_images": [
{
"url": "text",
"name": "text",
"mime_type": "text"
}
],
"compensation_method": "text",
"accepted_quantity": 1,
"rejected_quantity": 1,
"status_reason": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"return_labels": [
{
"courier": "text",
"service_level": "text",
"tracking_number": "text",
"type": "shipping",
"flags": [
"is_cancellable"
],
"documents": [
{
"url": "text",
"content_type": "application/pdf",
"type": [
"label"
],
"expires_at": "2025-10-11T19:34:53.524Z"
}
],
"destination_id": "text",
"line_item_ids": [
"text"
],
"is_free_label": false,
"label_cost_amount": "0.0",
"tracking_id": "text",
"external_reference": "text",
"delivery_status": "Pending",
"pickup_date": "2025-10-11",
"pickup_time": "19:34:53",
"is_pickup": false
}
],
"refund_method": "text",
"tags": [
"text"
],
"additional_fields": {},
"verification_code_used": "text",
"created_at": "2025-10-11T19:34:53.524Z",
"updated_at": "2025-10-11T19:34:53.524Z",
"mutations": [
{
"operation_id": "123e4567-e89b-12d3-a456-426614174000",
"result": {
"success": false,
"message": "",
"errors": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"type": "add_label",
"request": {
"type": "shipping",
"courier": "text",
"tracking_number": "text",
"service_level": "text",
"destination_id": "text",
"destination_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"template_id": "text",
"flags": [
"has_dangerous_goods"
],
"types": [
"code"
],
"line_item_ids": [
"text"
],
"additional_fields": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}
]
}Modify Return Registrations
You can use the available mutations (for example: generate a label) to update return registrations using the v4/returns/return-registrations/mutate endpoint.
Return Registrations represent a return request from a customer. There might be multiple return registrations for a single order. There might also be multiple labels for one return registration, if requested by the customer.
A return registration is linked to a configuration bundle (field 'code'), multiple configurations might be available on one account (e.g. country-specific courier configurations).
Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.
Certain fields of the return registration are not mutable via requests on the registration resource, but require 'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.
Authorizations
Body
Update (mutate) a return registration
Responses
200Success
application/json
400Error
application/json
403Error
application/json
404Error
application/json
post
POST /v4/returns/return-registrations/mutate/ HTTP/1.1
Host:
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 425
{
"mutations": [
{
"operation_id": "123e4567-e89b-12d3-a456-426614174000",
"result": {
"success": false,
"message": "",
"errors": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"type": "update_article_status",
"account": 1,
"request": {
"identifier": "text",
"identifier_type": "reference",
"tracking_number": "text",
"article_status_updates": [
{
"identifier": "text",
"identifier_type": "product_id",
"accepted_quantity": 0,
"rejected_quantity": 0,
"reason": "text"
}
]
}
}
]
}{
"account": 1,
"code": "text",
"version": null,
"client_key": "text",
"reference": "text",
"external_id": "123e4567-e89b-12d3-a456-426614174000",
"external_reference": "text",
"status": "created",
"status_reason": "text",
"original_courier": "text",
"original_order_id": null,
"order_date": null,
"order_currency": "text",
"order_total_amount": null,
"order_delivery_date": null,
"order_shipping_date": null,
"order_payment_method": [
"text"
],
"language_iso2": "text",
"customer_email": "[email protected]",
"customer_phone": "text",
"customer_salutation": "text",
"customer_first_name": "text",
"customer_last_name": "text",
"customer_country_iso3": "text",
"customer_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"articles_order": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"articles_return": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"return_reason": "text",
"return_reason_pretty": "text",
"return_quantity": 1,
"problem_description": "text",
"condition": "text",
"article_images": [
{
"url": "text",
"name": "text",
"mime_type": "text"
}
],
"compensation_method": "text",
"accepted_quantity": 1,
"rejected_quantity": 1,
"status_reason": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"return_labels": [
{
"courier": "text",
"service_level": "text",
"tracking_number": "text",
"type": "shipping",
"flags": [
"is_cancellable"
],
"documents": [
{
"url": "text",
"content_type": "application/pdf",
"type": [
"label"
],
"expires_at": "2025-10-11T19:34:53.524Z"
}
],
"destination_id": "text",
"line_item_ids": [
"text"
],
"is_free_label": false,
"label_cost_amount": "0.0",
"tracking_id": "text",
"external_reference": "text",
"delivery_status": "Pending",
"pickup_date": "2025-10-11",
"pickup_time": "19:34:53",
"is_pickup": false
}
],
"refund_method": "text",
"tags": [
"text"
],
"additional_fields": {},
"verification_code_used": "text",
"created_at": "2025-10-11T19:34:53.524Z",
"updated_at": "2025-10-11T19:34:53.524Z",
"mutations": [
{
"operation_id": "123e4567-e89b-12d3-a456-426614174000",
"result": {
"success": false,
"message": "",
"errors": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"type": "add_label",
"request": {
"type": "shipping",
"courier": "text",
"tracking_number": "text",
"service_level": "text",
"destination_id": "text",
"destination_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"template_id": "text",
"flags": [
"has_dangerous_goods"
],
"types": [
"code"
],
"line_item_ids": [
"text"
],
"additional_fields": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}
]
}Get Returns Article Information
You can retrieve the article information for a specific return registration using the v4/returns/return-registrations/{external_id}/article-info endpoint.
Retrieve all article rules for the return registration
Authorizations
Path parameters
external_idstring · uuidRequired
Unique identifier for this return registration, generated by parcelLab
Query parameters
draftbooleanOptionalDefault:
Set to true to preview behavior using unpublished configuration changes (e.g., article rules or courier options).
falseResponses
200Success
application/json
400Error
application/json
403Error
application/json
404Error
application/json
get
GET /v4/returns/return-registrations/{external_id}/article-info/ HTTP/1.1
Host:
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"article_returnability": [
{
"article": {
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"reasons": [
{
"type": "text",
"code": "text",
"path": "text",
"name": "text",
"name_localized": "text",
"note": "text",
"problem_description": "none",
"problem_description_min_length": 0,
"image_upload": "none",
"shopify_return_reason": "text",
"tags": [
"warranty-exclude"
]
}
],
"periods": {
"trial_period_days": 1,
"grace_period_days": 1,
"warranty_period_days": 1,
"is_in_trial_period": false,
"is_in_warranty_period": false
},
"has_compensation": true,
"compensation_methods": [
{
"category": "text",
"description": "text",
"description_localized": "text",
"external_code": "text",
"tags": [
"warranty-exclude"
]
}
],
"article_filters": [
{
"flag": "hidden",
"keep_article_max_limit": 1
}
]
}
],
"article_selection": [
{
"line_item_id": "text",
"selected": false,
"return_quantity": 0,
"return_reason": "text",
"problem_description": "",
"compensation_method": "text",
"article_images": [
"text"
],
"exchange_product_options": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"refund_methods": [
{
"code": "text",
"type": "original-payment-method",
"code_localized": "text",
"hint_localized": ""
}
],
"line_items_by_flag": [
{
"articles": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"flag": "out_of_returnable_period",
"title_localized": "text",
"description_localized": "text"
}
],
"split_returns_data": {
"ANY_ADDITIONAL_PROPERTY": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
]
}
}Partially Update Returns Article Information
You can partially update the article information for a specific return registration using the v4/returns/return-registrations/{external_id}/article-info endpoint.
Return Registrations represent a return request from a customer. There might be multiple return registrations for a single order. There might also be multiple labels for one return registration, if requested by the customer.
A return registration is linked to a configuration bundle (field 'code'), multiple configurations might be available on one account (e.g. country-specific courier configurations).
Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.
Certain fields of the return registration are not mutable via requests on the registration resource, but require 'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.
Authorizations
Path parameters
external_idstring · uuidRequired
Unique identifier for this return registration, generated by parcelLab
Query parameters
draftbooleanOptionalDefault:
Set to true to preview behavior using unpublished configuration changes (e.g., article rules or courier options).
falseBody
Update the selection of articles for a return registration
commitbooleanOptionalDefault:
Whether to commit the changes to the return registration (defaults to false, convenience flag clients)
falseResponses
200Success
application/json
400Error
application/json
403Error
application/json
404Error
application/json
patch
PATCH /v4/returns/return-registrations/{external_id}/article-info/ HTTP/1.1
Host:
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 261
{
"articles_return": [
{
"line_item_id": "text",
"selected": true,
"return_quantity": 0,
"return_reason": "text",
"problem_description": "",
"compensation_method": "text",
"article_images": [
"text"
],
"exchange_product_options": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"commit": false
}{
"article_returnability": [
{
"article": {
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"reasons": [
{
"type": "text",
"code": "text",
"path": "text",
"name": "text",
"name_localized": "text",
"note": "text",
"problem_description": "none",
"problem_description_min_length": 0,
"image_upload": "none",
"shopify_return_reason": "text",
"tags": [
"warranty-exclude"
]
}
],
"periods": {
"trial_period_days": 1,
"grace_period_days": 1,
"warranty_period_days": 1,
"is_in_trial_period": false,
"is_in_warranty_period": false
},
"has_compensation": true,
"compensation_methods": [
{
"category": "text",
"description": "text",
"description_localized": "text",
"external_code": "text",
"tags": [
"warranty-exclude"
]
}
],
"article_filters": [
{
"flag": "hidden",
"keep_article_max_limit": 1
}
]
}
],
"article_selection": [
{
"line_item_id": "text",
"selected": false,
"return_quantity": 0,
"return_reason": "text",
"problem_description": "",
"compensation_method": "text",
"article_images": [
"text"
],
"exchange_product_options": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"refund_methods": [
{
"code": "text",
"type": "original-payment-method",
"code_localized": "text",
"hint_localized": ""
}
],
"line_items_by_flag": [
{
"articles": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"flag": "out_of_returnable_period",
"title_localized": "text",
"description_localized": "text"
}
],
"split_returns_data": {
"ANY_ADDITIONAL_PROPERTY": [
{
"version": "v1",
"line_item_id": "text",
"product_id": "text",
"sku": "text",
"order_item_id": "text",
"article_name": "text",
"article_category": "text",
"article_store_url": "text",
"article_image_url": "text",
"article_brand": "text",
"size": "text",
"color": "text",
"width": 1,
"height": 1,
"length": 1,
"length_unit": "cm",
"weight": 1,
"weight_unit": "g",
"unit_price": "text",
"quantity": 1,
"amount_invoiced": "text",
"origin_country_iso3": "text",
"is_bulky": false,
"tags": [
"text"
],
"additional_attributes": [
{
"key": "text",
"value": null
}
],
"reference_date_for_return": "2025-10-11",
"reference_date_type": "order_date",
"fulfillment": "text",
"quantity_returned": 1,
"delivered_date": "2025-10-11",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
]
}
}Get Return Options
You can retrieve the carrier details for a specific return registration using the v4/returns/return-registrations/{external_id}/return-options endpoint.
Retrieve all courier information for the return registration
Authorizations
Path parameters
external_idstring · uuidRequired
Unique identifier for this return registration, generated by parcelLab
Query parameters
draftbooleanOptionalDefault:
Set to true to preview behavior using unpublished configuration changes (e.g., article rules or courier options).
falseResponses
200Success
application/json
400Error
application/json
403Error
application/json
404Error
application/json
get
GET /v4/returns/return-registrations/{external_id}/return-options/ HTTP/1.1
Host:
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"option_code": "",
"identifier": "",
"title": "",
"description": "",
"download_label_instructions": "",
"download_separate_label_instructions": "",
"download_label_button": "",
"download_packing_slip_instructions": "",
"download_packing_slip_button": "",
"qr_code_instructions": "",
"download_qr_code_button": "",
"additional_label": null,
"variants": [
{
"type": "pick-up",
"title": "text",
"description": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}Assign Return Options
You can apply the carrier details for a specific return registration using the v4/returns/return-registrations/{external_id}/return-options endpoint.
Return Registrations represent a return request from a customer. There might be multiple return registrations for a single order. There might also be multiple labels for one return registration, if requested by the customer.
A return registration is linked to a configuration bundle (field 'code'), multiple configurations might be available on one account (e.g. country-specific courier configurations).
Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.
Certain fields of the return registration are not mutable via requests on the registration resource, but require 'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.
Authorizations
Path parameters
external_idstring · uuidRequired
Unique identifier for this return registration, generated by parcelLab
Body
Responses
200Success
application/json
400Error
application/json
403Error
application/json
404Error
application/json
post
POST /v4/returns/return-registrations/{external_id}/return-options/ HTTP/1.1
Host:
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 41
{
"options_selected": [
{
"id": 1,
"index": 0
}
]
}{
"labels": [
{
"courier": "text",
"service_level": "text",
"tracking_number": "text",
"type": "shipping",
"flags": [
"is_cancellable"
],
"documents": [
{
"url": "text",
"content_type": "application/pdf",
"type": [
"label"
],
"expires_at": "2025-10-11T19:34:53.524Z"
}
],
"destination_id": "text",
"line_item_ids": [
"text"
],
"is_free_label": false,
"label_cost_amount": "0.0",
"tracking_id": "text",
"external_reference": "text",
"delivery_status": "Pending",
"pickup_date": "2025-10-11",
"pickup_time": "19:34:53",
"is_pickup": false
}
]
}Was this helpful?