PAparcellab
Return Registration

Mutate Return Registration (Batch)

Changed on

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.

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

Request

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

Request body

Response

accountinteger required

Account, that is linked to this registration.

configinteger nullable
codestring required

Configuration code of the return configuration

versionstring nullable
client_keystring required

Name of the client, as configured in account setup.

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

display_namestring required
sequence_numberstring required
status'created' | 'pending_payment' | 'submitted' | 'pending_approval' | 'pending_label' | 'approved' | 'rejected' | 'cancelled' | 'closed' | 'processing_failed' | 'invalid'
  • 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

cancellableboolean required
closableboolean required
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

is_gift_returns_portalboolean required
customer_phonestring

Customer phone number

customer_salutationstring
customer_first_namestring
customer_last_namestring
customer_country_iso3string

ISO 3166-1 alpha-3 code of country

customerstring required
destination_idstring nullable

Destination that articles without their own destination_id return to.

item_countinteger required
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

created_atstring date-time required
submitted_atstring date-time nullable required

Date(-time) when the customer submitted the return registration.

updated_atstring date-time required

Example response

{
  "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"
        }
      ]
    }
  ]
}

Changes