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.

List Return Registration

get

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

accountinteger[]Optional

clientintegerOptional

courierstringOptional

created_at_afterstring · date-timeOptional

created_at_beforestring · date-timeOptional

cursorstringOptional

The pagination cursor value.

customer_country_iso3stringOptional

customer_postal_codestringOptional

external_idstring · uuidOptional

external_referencestringOptional

language_iso2stringOptional

orderingstringOptional

Which field to use when ordering the results.

referencestringOptional

return_reasonstringOptional

return_reason_prettystringOptional

searchstringOptional

tagsstringOptional

tracking_numberstringOptional

updated_at_afterstring · date-timeOptional

updated_at_beforestring · date-timeOptional

Responses

200Success

application/json

400Error

application/json

403Error

application/json

404Error

application/json

get

/v4/returns/return-registrations/

GET /v4/returns/return-registrations/ HTTP/1.1
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_shipping_amount": null,
      "order_tax_amount": null,
      "order_delivery_date": null,
      "order_shipping_date": null,
      "order_payment_method": [
        "text"
      ],
      "language_iso2": "text",
      "is_gift_returns_portal": true,
      "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",
          "variant_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",
          "unit_price_original": "text",
          "quantity": 1,
          "amount_invoiced": "text",
          "tax_amount": "text",
          "harmonized_system_code": "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",
          "variant_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",
          "unit_price_original": "text",
          "quantity": 1,
          "amount_invoiced": "text",
          "tax_amount": "text",
          "harmonized_system_code": "text",
          "origin_country_iso3": "text",
          "is_bulky": false,
          "tags": [
            "text"
          ],
          "additional_attributes": [
            {
              "key": "text",
              "value": null
            }
          ],
          "reference_date_for_return": "2026-01-31",
          "reference_date_type": "order_date",
          "fulfillment": "text",
          "quantity_returned": 1,
          "delivered_date": "2026-01-31",
          "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": "2026-01-31T15:42:53.249Z"
            }
          ],
          "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": "2026-01-31",
          "pickup_time": "15:42:53",
          "is_pickup": false
        }
      ],
      "refund_method": "text",
      "tags": [
        "text"
      ],
      "additional_fields": {},
      "verification_code_used": "text",
      "created_at": "2026-01-31T15:42:53.249Z",
      "updated_at": "2026-01-31T15:42:53.249Z",
      "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.

Retrieve Return Registration

get

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

/v4/returns/return-registrations/{external_id}/

GET /v4/returns/return-registrations/{external_id}/ HTTP/1.1
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_shipping_amount": null,
  "order_tax_amount": null,
  "order_delivery_date": null,
  "order_shipping_date": null,
  "order_payment_method": [
    "text"
  ],
  "language_iso2": "text",
  "is_gift_returns_portal": true,
  "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "text",
      "origin_country_iso3": "text",
      "is_bulky": false,
      "tags": [
        "text"
      ],
      "additional_attributes": [
        {
          "key": "text",
          "value": null
        }
      ],
      "reference_date_for_return": "2026-01-31",
      "reference_date_type": "order_date",
      "fulfillment": "text",
      "quantity_returned": 1,
      "delivered_date": "2026-01-31",
      "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": "2026-01-31T15:42:53.249Z"
        }
      ],
      "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": "2026-01-31",
      "pickup_time": "15:42:53",
      "is_pickup": false
    }
  ],
  "refund_method": "text",
  "tags": [
    "text"
  ],
  "additional_fields": {},
  "verification_code_used": "text",
  "created_at": "2026-01-31T15:42:53.249Z",
  "updated_at": "2026-01-31T15:42:53.249Z",
  "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.

Register Return

post

Create a new return registration

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

courier_testingbooleanOptional

Set to true to use the test environment for carrier integration.

Default: false

draftbooleanOptional

Set to true to preview behavior using unpublished configuration changes (e.g., article rules or courier options).

Default: false

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 · nullableOptional

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 - Created
submitted - Submitted
pending_approval - Pending Approval
pending_label - Pending Label
approved - Approved
rejected - Rejected
cancelled - Cancelled
closed - Closed
processing_failed - Processing Failed

string · enumOptional

created - Created
submitted - Submitted
pending_approval - Pending Approval
pending_label - Pending Label
approved - Approved
rejected - Rejected
cancelled - Cancelled
closed - Closed
processing_failed - Processing Failed

Possible values:

status_reasonstring · max: 255Optional

Reason for the current status

original_courierstring · max: 255Optional

original_order_idstring · max: 255 · nullableOptional

order_datestring · nullableOptional

Date of the order

order_currencystring · max: 3Optional

Currency of the order, e.g. USD, EUR (ISO 4217)

order_total_amountstring · nullableOptional

Total amount of the original order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_shipping_amountstring · nullableOptional

Total shipping amount of the original order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_tax_amountstring · nullableOptional

Total tax amount of the original order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_delivery_datestring · nullableOptional

Date of the order delivery

order_shipping_datestring · nullableOptional

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

Order level tags.

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

/v4/returns/return-registrations/

POST /v4/returns/return-registrations/ HTTP/1.1
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.

Create Return Registration (from order)

post

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

/v4/returns/return-registrations/lookup-order/

POST /v4/returns/return-registrations/lookup-order/ HTTP/1.1
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_shipping_amount": null,
  "order_tax_amount": null,
  "order_delivery_date": null,
  "order_shipping_date": null,
  "order_payment_method": [
    "text"
  ],
  "language_iso2": "text",
  "is_gift_returns_portal": true,
  "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "text",
      "origin_country_iso3": "text",
      "is_bulky": false,
      "tags": [
        "text"
      ],
      "additional_attributes": [
        {
          "key": "text",
          "value": null
        }
      ],
      "reference_date_for_return": "2026-01-31",
      "reference_date_type": "order_date",
      "fulfillment": "text",
      "quantity_returned": 1,
      "delivered_date": "2026-01-31",
      "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": "2026-01-31T15:42:53.249Z"
        }
      ],
      "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": "2026-01-31",
      "pickup_time": "15:42:53",
      "is_pickup": false
    }
  ],
  "refund_method": "text",
  "tags": [
    "text"
  ],
  "additional_fields": {},
  "verification_code_used": "text",
  "created_at": "2026-01-31T15:42:53.249Z",
  "updated_at": "2026-01-31T15:42:53.249Z",
  "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.

Update Return Registration

put

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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 · nullableOptional

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 - Created
submitted - Submitted
pending_approval - Pending Approval
pending_label - Pending Label
approved - Approved
rejected - Rejected
cancelled - Cancelled
closed - Closed
processing_failed - Processing Failed

string · enumOptional

created - Created
submitted - Submitted
pending_approval - Pending Approval
pending_label - Pending Label
approved - Approved
rejected - Rejected
cancelled - Cancelled
closed - Closed
processing_failed - Processing Failed

Possible values:

status_reasonstring · max: 255Optional

Reason for the current status

original_courierstring · max: 255Optional

original_order_idstring · max: 255 · nullableOptional

order_datestring · nullableOptional

Date of the order

order_currencystring · max: 3Optional

Currency of the order, e.g. USD, EUR (ISO 4217)

order_total_amountstring · nullableOptional

Total amount of the original order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_shipping_amountstring · nullableOptional

Total shipping amount of the original order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_tax_amountstring · nullableOptional

Total tax amount of the original order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_delivery_datestring · nullableOptional

Date of the order delivery

order_shipping_datestring · nullableOptional

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

Order level tags.

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

/v4/returns/return-registrations/{external_id}/

PUT /v4/returns/return-registrations/{external_id}/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 3387

{
  "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_shipping_amount": null,
  "order_tax_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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "text",
      "origin_country_iso3": "text",
      "is_bulky": false,
      "tags": [
        "text"
      ],
      "additional_attributes": [
        {
          "key": "text",
          "value": null
        }
      ],
      "reference_date_for_return": "2026-01-31",
      "reference_date_type": "order_date",
      "fulfillment": "text",
      "quantity_returned": 1,
      "delivered_date": "2026-01-31",
      "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_shipping_amount": null,
  "order_tax_amount": null,
  "order_delivery_date": null,
  "order_shipping_date": null,
  "order_payment_method": [
    "text"
  ],
  "language_iso2": "text",
  "is_gift_returns_portal": true,
  "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "text",
      "origin_country_iso3": "text",
      "is_bulky": false,
      "tags": [
        "text"
      ],
      "additional_attributes": [
        {
          "key": "text",
          "value": null
        }
      ],
      "reference_date_for_return": "2026-01-31",
      "reference_date_type": "order_date",
      "fulfillment": "text",
      "quantity_returned": 1,
      "delivered_date": "2026-01-31",
      "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": "2026-01-31T15:42:53.249Z"
        }
      ],
      "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": "2026-01-31",
      "pickup_time": "15:42:53",
      "is_pickup": false
    }
  ],
  "refund_method": "text",
  "tags": [
    "text"
  ],
  "additional_fields": {},
  "verification_code_used": "text",
  "created_at": "2026-01-31T15:42:53.249Z",
  "updated_at": "2026-01-31T15:42:53.249Z",
  "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.

Partially Update Return Registration

patch

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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 · nullableOptional

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 - Created
submitted - Submitted
pending_approval - Pending Approval
pending_label - Pending Label
approved - Approved
rejected - Rejected
cancelled - Cancelled
closed - Closed
processing_failed - Processing Failed

string · enumOptional

created - Created
submitted - Submitted
pending_approval - Pending Approval
pending_label - Pending Label
approved - Approved
rejected - Rejected
cancelled - Cancelled
closed - Closed
processing_failed - Processing Failed

Possible values:

status_reasonstring · max: 255Optional

Reason for the current status

original_courierstring · max: 255Optional

original_order_idstring · max: 255 · nullableOptional

order_datestring · nullableOptional

Date of the order

order_currencystring · max: 3Optional

Currency of the order, e.g. USD, EUR (ISO 4217)

order_total_amountstring · nullableOptional

Total amount of the original order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_shipping_amountstring · nullableOptional

Total shipping amount of the original order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_tax_amountstring · nullableOptional

Total tax amount of the original order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_delivery_datestring · nullableOptional

Date of the order delivery

order_shipping_datestring · nullableOptional

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

Order level tags.

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

/v4/returns/return-registrations/{external_id}/

PATCH /v4/returns/return-registrations/{external_id}/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 3387

{
  "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_shipping_amount": null,
  "order_tax_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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "text",
      "origin_country_iso3": "text",
      "is_bulky": false,
      "tags": [
        "text"
      ],
      "additional_attributes": [
        {
          "key": "text",
          "value": null
        }
      ],
      "reference_date_for_return": "2026-01-31",
      "reference_date_type": "order_date",
      "fulfillment": "text",
      "quantity_returned": 1,
      "delivered_date": "2026-01-31",
      "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_shipping_amount": null,
  "order_tax_amount": null,
  "order_delivery_date": null,
  "order_shipping_date": null,
  "order_payment_method": [
    "text"
  ],
  "language_iso2": "text",
  "is_gift_returns_portal": true,
  "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "text",
      "origin_country_iso3": "text",
      "is_bulky": false,
      "tags": [
        "text"
      ],
      "additional_attributes": [
        {
          "key": "text",
          "value": null
        }
      ],
      "reference_date_for_return": "2026-01-31",
      "reference_date_type": "order_date",
      "fulfillment": "text",
      "quantity_returned": 1,
      "delivered_date": "2026-01-31",
      "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": "2026-01-31T15:42:53.249Z"
        }
      ],
      "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": "2026-01-31",
      "pickup_time": "15:42:53",
      "is_pickup": false
    }
  ],
  "refund_method": "text",
  "tags": [
    "text"
  ],
  "additional_fields": {},
  "verification_code_used": "text",
  "created_at": "2026-01-31T15:42:53.249Z",
  "updated_at": "2026-01-31T15:42:53.249Z",
  "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 Return Registration

post

Mutate this return registration with one of the available mutations

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

/v4/returns/return-registrations/{external_id}/mutate/

POST /v4/returns/return-registrations/{external_id}/mutate/ HTTP/1.1
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_shipping_amount": null,
  "order_tax_amount": null,
  "order_delivery_date": null,
  "order_shipping_date": null,
  "order_payment_method": [
    "text"
  ],
  "language_iso2": "text",
  "is_gift_returns_portal": true,
  "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "text",
      "origin_country_iso3": "text",
      "is_bulky": false,
      "tags": [
        "text"
      ],
      "additional_attributes": [
        {
          "key": "text",
          "value": null
        }
      ],
      "reference_date_for_return": "2026-01-31",
      "reference_date_type": "order_date",
      "fulfillment": "text",
      "quantity_returned": 1,
      "delivered_date": "2026-01-31",
      "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": "2026-01-31T15:42:53.249Z"
        }
      ],
      "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": "2026-01-31",
      "pickup_time": "15:42:53",
      "is_pickup": false
    }
  ],
  "refund_method": "text",
  "tags": [
    "text"
  ],
  "additional_fields": {},
  "verification_code_used": "text",
  "created_at": "2026-01-31T15:42:53.249Z",
  "updated_at": "2026-01-31T15:42:53.249Z",
  "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.

Mutate Return Registration (Batch)

post

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Update (mutate) a return registration

Responses

200Success

application/json

400Error

application/json

403Error

application/json

404Error

application/json

post

/v4/returns/return-registrations/mutate/

POST /v4/returns/return-registrations/mutate/ HTTP/1.1
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_shipping_amount": null,
  "order_tax_amount": null,
  "order_delivery_date": null,
  "order_shipping_date": null,
  "order_payment_method": [
    "text"
  ],
  "language_iso2": "text",
  "is_gift_returns_portal": true,
  "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "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",
      "variant_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",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "text",
      "origin_country_iso3": "text",
      "is_bulky": false,
      "tags": [
        "text"
      ],
      "additional_attributes": [
        {
          "key": "text",
          "value": null
        }
      ],
      "reference_date_for_return": "2026-01-31",
      "reference_date_type": "order_date",
      "fulfillment": "text",
      "quantity_returned": 1,
      "delivered_date": "2026-01-31",
      "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": "2026-01-31T15:42:53.249Z"
        }
      ],
      "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": "2026-01-31",
      "pickup_time": "15:42:53",
      "is_pickup": false
    }
  ],
  "refund_method": "text",
  "tags": [
    "text"
  ],
  "additional_fields": {},
  "verification_code_used": "text",
  "created_at": "2026-01-31T15:42:53.249Z",
  "updated_at": "2026-01-31T15:42:53.249Z",
  "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 Article Info

get

Retrieve all article rules for the return registration

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

external_idstring · uuidRequired

Unique identifier for this return registration, generated by parcelLab

Query parameters

draftbooleanOptional

Set to true to preview behavior using unpublished configuration changes (e.g., article rules or courier options).

Default: false

Responses

200Success

application/json

400Error

application/json

403Error

application/json

404Error

application/json

get

/v4/returns/return-registrations/{external_id}/article-info/

GET /v4/returns/return-registrations/{external_id}/article-info/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "article_returnability": [
    {
      "article": {
        "version": "v1",
        "line_item_id": "text",
        "product_id": "text",
        "variant_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",
        "unit_price_original": "text",
        "quantity": 1,
        "amount_invoiced": "text",
        "tax_amount": "text",
        "harmonized_system_code": "text",
        "origin_country_iso3": "text",
        "is_bulky": false,
        "tags": [
          "text"
        ],
        "additional_attributes": [
          {
            "key": "text",
            "value": null
          }
        ],
        "reference_date_for_return": "2026-01-31",
        "reference_date_type": "order_date",
        "fulfillment": "text",
        "quantity_returned": 1,
        "delivered_date": "2026-01-31",
        "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",
          "variant_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",
          "unit_price_original": "text",
          "quantity": 1,
          "amount_invoiced": "text",
          "tax_amount": "text",
          "harmonized_system_code": "text",
          "origin_country_iso3": "text",
          "is_bulky": false,
          "tags": [
            "text"
          ],
          "additional_attributes": [
            {
              "key": "text",
              "value": null
            }
          ],
          "reference_date_for_return": "2026-01-31",
          "reference_date_type": "order_date",
          "fulfillment": "text",
          "quantity_returned": 1,
          "delivered_date": "2026-01-31",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "flag": "already_returned",
      "title_localized": "text",
      "description_localized": "text"
    }
  ],
  "split_groups": [
    {
      "key": "text",
      "display_name": "text",
      "articles": [
        {
          "version": "v1",
          "line_item_id": "text",
          "product_id": "text",
          "variant_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",
          "unit_price_original": "text",
          "quantity": 1,
          "amount_invoiced": "text",
          "tax_amount": "text",
          "harmonized_system_code": "text",
          "origin_country_iso3": "text",
          "is_bulky": false,
          "tags": [
            "text"
          ],
          "additional_attributes": [
            {
              "key": "text",
              "value": null
            }
          ],
          "reference_date_for_return": "2026-01-31",
          "reference_date_type": "order_date",
          "fulfillment": "text",
          "quantity_returned": 1,
          "delivered_date": "2026-01-31",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ]
    }
  ],
  "requires_split_group_selection": false
}

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.

Validate Article Info (Return items)

patch

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

external_idstring · uuidRequired

Unique identifier for this return registration, generated by parcelLab

Query parameters

draftbooleanOptional

Set to true to preview behavior using unpublished configuration changes (e.g., article rules or courier options).

Default: false

Body

Update the selection of articles for a return registration

commitbooleanOptional

Whether to commit the changes to the return registration (defaults to false, convenience flag clients)

Default: false

Responses

200Success

application/json

400Error

application/json

403Error

application/json

404Error

application/json

patch

/v4/returns/return-registrations/{external_id}/article-info/

PATCH /v4/returns/return-registrations/{external_id}/article-info/ HTTP/1.1
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",
        "variant_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",
        "unit_price_original": "text",
        "quantity": 1,
        "amount_invoiced": "text",
        "tax_amount": "text",
        "harmonized_system_code": "text",
        "origin_country_iso3": "text",
        "is_bulky": false,
        "tags": [
          "text"
        ],
        "additional_attributes": [
          {
            "key": "text",
            "value": null
          }
        ],
        "reference_date_for_return": "2026-01-31",
        "reference_date_type": "order_date",
        "fulfillment": "text",
        "quantity_returned": 1,
        "delivered_date": "2026-01-31",
        "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",
          "variant_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",
          "unit_price_original": "text",
          "quantity": 1,
          "amount_invoiced": "text",
          "tax_amount": "text",
          "harmonized_system_code": "text",
          "origin_country_iso3": "text",
          "is_bulky": false,
          "tags": [
            "text"
          ],
          "additional_attributes": [
            {
              "key": "text",
              "value": null
            }
          ],
          "reference_date_for_return": "2026-01-31",
          "reference_date_type": "order_date",
          "fulfillment": "text",
          "quantity_returned": 1,
          "delivered_date": "2026-01-31",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "flag": "already_returned",
      "title_localized": "text",
      "description_localized": "text"
    }
  ],
  "split_groups": [
    {
      "key": "text",
      "display_name": "text",
      "articles": [
        {
          "version": "v1",
          "line_item_id": "text",
          "product_id": "text",
          "variant_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",
          "unit_price_original": "text",
          "quantity": 1,
          "amount_invoiced": "text",
          "tax_amount": "text",
          "harmonized_system_code": "text",
          "origin_country_iso3": "text",
          "is_bulky": false,
          "tags": [
            "text"
          ],
          "additional_attributes": [
            {
              "key": "text",
              "value": null
            }
          ],
          "reference_date_for_return": "2026-01-31",
          "reference_date_type": "order_date",
          "fulfillment": "text",
          "quantity_returned": 1,
          "delivered_date": "2026-01-31",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ]
    }
  ],
  "requires_split_group_selection": false
}

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 Return Options

get

Retrieve all courier information for the return registration

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

external_idstring · uuidRequired

Unique identifier for this return registration, generated by parcelLab

Query parameters

draftbooleanOptional

Set to true to preview behavior using unpublished configuration changes (e.g., article rules or courier options).

Default: false

Responses

200Success

application/json

400Error

application/json

403Error

application/json

404Error

application/json

get

/v4/returns/return-registrations/{external_id}/return-options/

GET /v4/returns/return-registrations/{external_id}/return-options/ HTTP/1.1
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.

Apply Return Option

post

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

/v4/returns/return-registrations/{external_id}/return-options/

POST /v4/returns/return-registrations/{external_id}/return-options/ HTTP/1.1
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": "2026-01-31T15:42:53.249Z"
        }
      ],
      "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": "2026-01-31",
      "pickup_time": "15:42:53",
      "is_pickup": false
    }
  ]
}

PreviousReturn Configurations

Was this helpful?

hashtagOverview

hashtagGet Return Registrations

hashtagList Return Registration

hashtagGet a Return Registration

hashtagRetrieve Return Registration

hashtagCreate a Return Registration

hashtagRegister Return

hashtagCreate a Return Registration via Order Information

hashtagCreate Return Registration (from order)

hashtagUpdate a Return Registration

hashtagUpdate Return Registration

hashtagPartially Update a Return Registration

hashtagPartially Update Return Registration

hashtagModify a Return Registration

hashtagMutate Return Registration

hashtagModify Return Registrations

hashtagMutate Return Registration (Batch)

hashtagGet Returns Article Information

hashtagRetrieve Article Info

hashtagPartially Update Returns Article Information

hashtagValidate Article Info (Return items)

hashtagGet Return Options

hashtagRetrieve Return Options

hashtagAssign Return Options

hashtagApply Return Option

Overview

Get Return Registrations

List Return Registration

Get a Return Registration

Retrieve Return Registration

Create a Return Registration

Register Return

Create a Return Registration via Order Information

Create Return Registration (from order)

Update a Return Registration

Update Return Registration

Partially Update a Return Registration

Partially Update Return Registration

Modify a Return Registration

Mutate Return Registration

Modify Return Registrations

Mutate Return Registration (Batch)

Get Returns Article Information

Retrieve Article Info

Partially Update Returns Article Information

Validate Article Info (Return items)

Get Return Options

Retrieve Return Options

Assign Return Options

Apply Return Option