Process Return Mutations

Process received returns with return registration mutations, including closing a submitted return and recording warehouse receive status.

Use return registration mutations when a warehouse, store, or WMS has received a return and needs to update parcelLab.

There are two mutation endpoints:

Use case	Endpoint	Result
Close and settle one submitted return	POST /v4/returns/return-registrations/{external_id}/mutate/	Closes the return registration and triggers connected refund or exchange processing where configured.
Record receive status only	POST /v4/returns/return-registrations/mutate/	Updates article receive status and tracking receive status. It does not close the return.

The Receive UI in the Returns Portal snippet performs the warehouse receive action in the parcelLab UI. Use this API page when your warehouse, store, or WMS performs the receipt and needs to call parcelLab directly.

Before You Start

You need:

• An API token with access to the Returns API.

• The account ID.

• The return registration external_id.

• A return registration created from a Returns Portal configuration.

• The return registration must be in submitted or approved status before it can be closed.

• Article identifiers, such as line_item_id, for accepted or rejected quantity updates.

Store the external_id returned when creating or submitting the return registration. It is the safest identifier for processing calls because order references and tracking numbers can be reused across repeated test attempts or partial flows.

Resolve the Return Registration

If your system already stores the return registration external_id, use it directly.

If your warehouse or store system only has a return tracking number, first resolve the tracking record and use its identifiersConsignment value as the return registration external_id.

Resolve by tracking number

GET /v3/track/trackings/?account=123456&tracking_number=RET-123456

Example response fields:

{
  "results": [
    {
      "trackingNumber": "RET-123456",
      "orderNumber": "O-123123",
      "identifiersConsignment": "95c35493-41aa-44f8-9154-5a25cbbc1865"
    }
  ]
}

Close a Return

Use close_return when the returned goods have been received and the return should be finalized. Closing a return is different from updating article receive status: closing finalizes the return registration, triggers the connected order system where configured, and moves the return toward completion.

Endpoint: POST /v4/returns/return-registrations/{external_id}/mutate/

Operation: returns_return_registrations_mutate_create

Mutate Return Registration

post

Mutate this return registration with one of the available mutations

Authorizations

HeaderTokenOAuth2 Authentication

AuthorizationstringRequired

Send Authorization: Parcellab-API-Token <encoded-token>.

<encoded-token> = base64(account_id:token) as provided in the portal.

Path parameters

external_idstring · uuidRequired

Unique identifier for this return registration, generated by parcelLab

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Update (mutate) a return registration

Responses

200Success

application/json

Represents a return registration

accountintegerRequired

Account, that is linked to this registration.

configinteger · nullableOptional

codestring · max: 255Required

Configuration code of the return configuration

versionstring · nullableOptional

client_keystringRead-onlyRequired

Name of the client, as configured in account setup.

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

sequence_numberstringRead-onlyRequired

statusstring · 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
• invalid - Invalid

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

is_gift_returns_portalbooleanRead-onlyRequired

customer_emailany ofRequired

Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.

string · emailOptional

or

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

customer_addressany ofRequired

or

object · EmptyOptional

refund_methodstring · max: 255Optional

Refund method selected by customer

tagsstring[]Optional

Order level tags.

verification_code_usedstring · max: 255Optional

Verification code (e.g. zip/email) used for this return registration

created_atstring · date-timeRead-onlyRequired

updated_atstring · date-timeRead-onlyRequired

400Error

application/json

403Error

application/json

404Error

application/json

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

HTTPcURLJavaScriptPython

POST /v4/returns/return-registrations/{external_id}/mutate/ HTTP/1.1
Authorization: Parcellab-API-Token YOUR_BASE64_ENCODED_API_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 701

{
  "mutations": [
    {
      "operation_id": "123e4567-e89b-12d3-a456-426614174000",
      "result": {
        "success": false,
        "message": "",
        "errors": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "warnings": [
          "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"
        ],
        "label_types": [
          "code"
        ],
        "line_item_ids": [
          "text"
        ],
        "additional_fields": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    }
  ]
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

{
  "account": 1,
  "config": null,
  "code": "text",
  "version": null,
  "client_key": "text",
  "reference": "text",
  "external_id": "123e4567-e89b-12d3-a456-426614174000",
  "external_reference": "text",
  "sequence_number": "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": "[e-mail]",
  "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": [
    {
      "article_name": "Blue T-Shirt",
      "line_item_id": "ITEM-001",
      "product_id": "PROD-123",
      "quantity": 2,
      "sku": "TSHIRT-BLUE-M"
    }
  ],
  "articles_return": [
    {
      "article_name": "Blue T-Shirt",
      "line_item_id": "ITEM-001",
      "product_id": "PROD-123",
      "quantity": 2,
      "sku": "TSHIRT-BLUE-M"
    }
  ],
  "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-07-18T16:39:55.526Z"
        }
      ],
      "locations_url": "text",
      "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-07-18",
      "earliest_pickup_time": "16:39:55",
      "latest_pickup_time": "16:39:55",
      "pickup_confirmation_code": "text",
      "is_pickup": false,
      "configuration_id": 1,
      "group_code": "text",
      "courier_code_overwrite": "text"
    }
  ],
  "refund_method": "text",
  "tags": [
    "text"
  ],
  "additional_fields": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "verification_code_used": "text",
  "created_at": "2026-07-18T16:39:55.526Z",
  "updated_at": "2026-07-18T16:39:55.526Z",
  "mutations": [
    {
      "operation_id": "123e4567-e89b-12d3-a456-426614174000",
      "result": {
        "success": false,
        "message": "",
        "errors": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "warnings": [
          "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"
        ],
        "label_types": [
          "code"
        ],
        "line_item_ids": [
          "text"
        ],
        "additional_fields": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    }
  ]
}

Request Fields

Field	Required	Type	Description
type	yes	string	Use close_return.
status_reason	no	string	Reason recorded for closing the return.
trigger_refund	no	boolean	Whether to issue a monetary refund when closing the return.
release_exchange_items	no	boolean	Whether to release exchange items when closing the return.
refund_shipping_fees	no	boolean	Whether to refund the original order shipping cost.
tracking_number	no	string	Return tracking number used for receive-status synchronization when article status updates are included.
received_by	no	string	Source shown in receive status.
receive_note	no	string	Receive note stored with the return registration and tracking receive status.
article_status_updates	no	array	Accepted or rejected quantities to apply before closing.

Article Status Update Fields

Field	Required	Type	Description
identifier	yes	string	Article identifier to update.
identifier_type	yes	string	Identifier type. Use line_item_id or product_id.
accepted_quantity	no	integer	Quantity accepted by the warehouse or store.
rejected_quantity	no	integer	Quantity rejected by the warehouse or store.
reason	no	string	Reason for rejection or adjustment.

Example close request with accepted quantities

{
  "mutations": [
    {
      "type": "close_return",
      "status_reason": "Closed from warehouse receipt",
      "trigger_refund": true,
      "release_exchange_items": true,
      "refund_shipping_fees": false,
      "tracking_number": "RET-123456",
      "received_by": "Warehouse API",
      "receive_note": "Received by warehouse API for order O-123123.",
      "article_status_updates": [
        {
          "identifier": "LI-1",
          "identifier_type": "line_item_id",
          "accepted_quantity": 1,
          "rejected_quantity": 0,
          "reason": null
        }
      ]
    }
  ]
}

Example response (trimmed)

{
  "external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
  "reference": "O-123123",
  "status": "closed",
  "mutations": [
    {
      "type": "close_return",
      "result": {
        "success": true,
        "message": "",
        "errors": {},
        "warnings": []
      }
    }
  ]
}

Check mutations[].result.success in the response. A successful HTTP response can still include a mutation-level result that explains why a requested mutation was not applied.

Record Receive Status Without Closing

Use the batch mutate endpoint only when you want to record receive status without closing the RMA.

The batch endpoint can update receive status and article accepted or rejected quantities for a registration, but it does not close the return or trigger refund or exchange processing.

Endpoint: POST /v4/returns/return-registrations/mutate/

Operation: mutate_batch

Mutate Return Registration (Batch)

post

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

HeaderTokenOAuth2 Authentication

AuthorizationstringRequired

Send Authorization: Parcellab-API-Token <encoded-token>.

<encoded-token> = base64(account_id:token) as provided in the portal.

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Update (mutate) a return registration

Responses

200Success

application/json

Represents a return registration

accountintegerRequired

Account, that is linked to this registration.

configinteger · nullableOptional

codestring · max: 255Required

Configuration code of the return configuration

versionstring · nullableOptional

client_keystringRead-onlyRequired

Name of the client, as configured in account setup.

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

sequence_numberstringRead-onlyRequired

statusstring · 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
• invalid - Invalid

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

is_gift_returns_portalbooleanRead-onlyRequired

customer_emailany ofRequired

Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.

string · emailOptional

or

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

customer_addressany ofRequired

or

object · EmptyOptional

refund_methodstring · max: 255Optional

Refund method selected by customer

tagsstring[]Optional

Order level tags.

verification_code_usedstring · max: 255Optional

Verification code (e.g. zip/email) used for this return registration

created_atstring · date-timeRead-onlyRequired

updated_atstring · date-timeRead-onlyRequired

400Error

application/json

403Error

application/json

404Error

application/json

post/v4/returns/return-registrations/mutate/

HTTPcURLJavaScriptPython

POST /v4/returns/return-registrations/mutate/ HTTP/1.1
Authorization: Parcellab-API-Token YOUR_BASE64_ENCODED_API_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 715

{
  "mutations": [
    {
      "operation_id": "123e4567-e89b-12d3-a456-426614174000",
      "result": {
        "success": false,
        "message": "",
        "errors": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "warnings": [
          "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"
          }
        ],
        "receive_status": {
          "received_by": "",
          "received_at": "2026-07-18T16:39:55.526Z",
          "status": "partially_received",
          "receive_note": "text",
          "receive_images": [
            {
              "url": "text",
              "name": "text",
              "mime_type": "text"
            }
          ],
          "is_fully_received": true,
          "label_notes": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      }
    }
  ]
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

{
  "account": 1,
  "config": null,
  "code": "text",
  "version": null,
  "client_key": "text",
  "reference": "text",
  "external_id": "123e4567-e89b-12d3-a456-426614174000",
  "external_reference": "text",
  "sequence_number": "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": "[e-mail]",
  "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": [
    {
      "article_name": "Blue T-Shirt",
      "line_item_id": "ITEM-001",
      "product_id": "PROD-123",
      "quantity": 2,
      "sku": "TSHIRT-BLUE-M"
    }
  ],
  "articles_return": [
    {
      "article_name": "Blue T-Shirt",
      "line_item_id": "ITEM-001",
      "product_id": "PROD-123",
      "quantity": 2,
      "sku": "TSHIRT-BLUE-M"
    }
  ],
  "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-07-18T16:39:55.526Z"
        }
      ],
      "locations_url": "text",
      "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-07-18",
      "earliest_pickup_time": "16:39:55",
      "latest_pickup_time": "16:39:55",
      "pickup_confirmation_code": "text",
      "is_pickup": false,
      "configuration_id": 1,
      "group_code": "text",
      "courier_code_overwrite": "text"
    }
  ],
  "refund_method": "text",
  "tags": [
    "text"
  ],
  "additional_fields": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "verification_code_used": "text",
  "created_at": "2026-07-18T16:39:55.526Z",
  "updated_at": "2026-07-18T16:39:55.526Z",
  "mutations": [
    {
      "operation_id": "123e4567-e89b-12d3-a456-426614174000",
      "result": {
        "success": false,
        "message": "",
        "errors": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "warnings": [
          "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"
        ],
        "label_types": [
          "code"
        ],
        "line_item_ids": [
          "text"
        ],
        "additional_fields": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    }
  ]
}

Example batch receive-status update

{
  "mutations": [
    {
      "account": 123456,
      "type": "update_article_status",
      "request": {
        "identifier": "95c35493-41aa-44f8-9154-5a25cbbc1865",
        "identifier_type": "external_id",
        "tracking_number": "RET-123456",
        "article_status_updates": [
          {
            "identifier": "LI-1",
            "identifier_type": "line_item_id",
            "accepted_quantity": 1,
            "rejected_quantity": 0,
            "reason": null
          }
        ],
        "receive_status": {
          "received_by": "Warehouse API",
          "received_at": "2026-06-09T12:00:00Z",
          "status": "completely_accepted",
          "receive_note": "Received by warehouse API for order O-123123.",
          "receive_images": [],
          "is_fully_received": true
        }
      }
    }
  ]
}

Use identifier_type: "external_id" when possible. The batch endpoint also requires tracking_number because it updates the matching return tracking record.

Related Flows

• Headless Returns Flow explains the full create, submit, label, exchange, and follow-up flow.

• Return Registrations lists the available return registration API endpoints.

• Real-time API Connection for Returns describes the inverse flow where parcelLab sends close instructions to your OMS or refund orchestration layer.

• The older Process Return API documents the Returns API v2 closeById endpoint. Use the v4 mutation endpoints on this page for new return registration integrations.