Return Registration

Register Return

Changed on Nov 3, 2026

Create a new return registration

post/v4/returns/return-registrations/

Request

The document declares no server URL.
Auth
- API key in header Authorization
- or HTTP bearer

Query parameters

courier_testingboolean

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

draftboolean

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

pre_register_backend_trackingboolean

Create backend tracking for this registration before it is submitted.

return_init_v2boolean

Run returns_order_init_v2 apps after creation.

Request body

accountinteger required

Account, that is linked to this registration.

configinteger nullable

codestring required

Configuration code of the return configuration

versionstring nullable

referencestring required

Retailer reference, e.g. the order number, not unique

external_idstring uuid

Unique identifier for this return registration, generated by parcelLab

external_referencestring

Additional identifier (e.g. shop system id) for this return registration, generated by the retailer

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

status_reasonstring

Reason for the current status

original_courierstring

original_order_idstring nullable

order_datestring date-time nullable

Date of the order

order_currencystring

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

order_total_amountstring decimal nullable

Total amount of the original order

order_shipping_amountstring decimal nullable

Total shipping amount of the original order

order_tax_amountstring decimal nullable

Total tax amount of the original order

order_delivery_datestring date-time nullable

Date of the order delivery

order_shipping_datestring date-time nullable

Date of the order shipment

order_payment_methodstring[]

Payment method used for the order, as setup as reference items in the accounts configuration

language_iso2string

ISO 639-1 language code of the recipient, if known, required for localized communication

customer_phonestring

Customer phone number

customer_salutationstring

customer_first_namestring

customer_last_namestring

customer_country_iso3string

ISO 3166-1 alpha-3 code of country

destination_idstring nullable

Destination that articles without their own destination_id return to.

refund_methodstring

Refund method selected by customer

tagsstring[]

Order level tags.

additional_fieldsobject

Free-form JSON object for custom return-registration metadata. Send a JSON object keyed by your field names; values may be scalars, arrays, or nested objects. This is not the order API additional_attributes list of {key, value} pairs.

verification_code_usedstring

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

Example request

{
  "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"
    }
  ],
  "mutations": [
    {
      "items": [
        {
          "article_name": "Blue T-Shirt",
          "line_item_id": "ITEM-001",
          "product_id": "PROD-123",
          "quantity": 2,
          "sku": "TSHIRT-BLUE-M"
        }
      ]
    }
  ]
}

Response