Headless Returns Flow

This flow explains the interaction with the parcelLab Returns platform in a headless manner, using a custom user interface instead of the parcelLab plugin.

1) Create Return Registration (from order)

Creating a return registration opens up a returns process and prepares order data for user choices like what items to return and how to be compensated. It can be considered the login to the returns portal.

Providing correct order and user data in the request is considered a secure login and should be treated as such.

Endpoint: POST /v4/returns/return-registrations/lookup-order/

Operation: returns_return_registrations_lookup_order_create

View full documentation for "Create Return Registration (from order)"

Result: ReturnRegistration with an external_id (store this as primary identifier for the whole returns process)

Example request

{
  "account": 161912,
  "code": "de-de",
  "identifier": {
    "reference": "O-123123",
    "identifier": "[e-mail]"
  }
}

Example response (trimmed)

{
  "external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
  "reference": "O-123123",
  "status": "created",
  "articles_order": [
    {
      "line_item_id": "LI-1",
      "article_name": "T-Shirt",
      "quantity": 1
    }
  ]
}

1b) Register Return (without order lookup)

Use this endpoint when your backend already has all order and customer data and you want to create a return registration directly.

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

Operation: returns_return_registrations_create

View full documentation for "Register Return"

Result: ReturnRegistration created directly from payload data (without order lookup)

Example request

{
  "account": 161912,
  "code": "de-de",
  "reference": "O-123123",
  "customer_email": "[e-mail]",
  "customer_country_iso3": "DEU",
  "customer_address": {
    "address_line": "Musterstrasse 1",
    "postal_code": "10115",
    "city": "Berlin",
    "country_iso3": "DEU"
  },
  "articles_order": [
    {
      "line_item_id": "LI-1",
      "article_name": "T-Shirt",
      "quantity": 1
    }
  ]
}

Example response (trimmed)

{
  "external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
  "reference": "O-123123",
  "status": "created",
  "customer_email": "[e-mail]",
  "articles_order": [
    {
      "line_item_id": "LI-1",
      "article_name": "T-Shirt",
      "quantity": 1
    }
  ]
}

2) Retrieve Article Info (returnability rules + reasons + compensation)

Retrieve the article-level rules before the customer selects what to return. This includes return reasons, return periods, compensation options, and split-group metadata.

Endpoint: GET /v4/returns/return-registrations/{external_id}/article-info/

Operation: returns_return_registrations_article_info_retrieve

View full documentation for "Retrieve Article Info"

Result: ReturnRegistrationReturnability with returnability rules and current selection state

Example request

GET /v4/returns/return-registrations/95c35493-41aa-44f8-9154-5a25cbbc1865/article-info/

Example response (trimmed)

{
  "article_returnability": [
    {
      "article": {
        "line_item_id": "LI-1",
        "article_name": "T-Shirt",
        "quantity": 1
      },
      "periods": {
        "trial_period_days": 30,
        "grace_period_days": 14,
        "is_in_trial_period": true,
        "is_in_warranty_period": false
      },
      "reasons": [
        {
          "type": "reason",
          "code": "too_small",
          "path": "size/too_small",
          "name": "Too small",
          "name_localized": "Too small",
          "note": "Shown in the UI",
          "problem_description": "optional"
        }
      ],
      "compensation_methods": [
        {
          "category": "refund",
          "description": "Refund",
          "description_localized": "Refund",
          "external_code": "refund"
        }
      ],
      "article_filters": []
    }
  ],
  "refund_methods": [
    {
      "code": "refund",
      "type": "original-payment-method",
      "code_localized": "Refund"
    }
  ],
  "requires_split_group_selection": false
}

3) Validate Article Info (Return items)

As the customer selects items, quantities, reasons, and compensation, send those choices here to validate and optionally persist (commit: true) them.

Endpoint: PATCH /v4/returns/return-registrations/{external_id}/article-info/

Operation: returns_return_registrations_article_info_partial_update

View full documentation for "Validate Article Info (Return items)"

Result: updated ReturnRegistrationReturnability, including the selection state you submitted

Example request

{
  "commit": true,
  "articles_return": [
    {
      "line_item_id": "LI-1",
      "selected": true,
      "return_quantity": 1,
      "return_reason": "too_small",
      "compensation_method": "refund"
    }
  ]
}

Example response (trimmed)

{
  "article_selection": [
    {
      "line_item_id": "LI-1",
      "selected": true,
      "return_quantity": 1,
      "return_reason": "too_small",
      "compensation_method": "refund"
    }
  ],
  "article_returnability": [
    {
      "article": {
        "line_item_id": "LI-1"
      },
      "reasons": [
        {
          "code": "too_small"
        }
      ]
    }
  ],
  "requires_split_group_selection": false
}

4) Retrieve Return Options (courier / drop-off / pickup)

After article selection is valid, retrieve available return methods for this registration. The returned option id is used in the next step.

Endpoint: GET /v4/returns/return-registrations/{external_id}/return-options/

Operation: returns_return_registrations_return_options_retrieve

View full documentation for "Retrieve Return Options"

Result: available return options (couriers/methods) for this registration

Example request

GET /v4/returns/return-registrations/95c35493-41aa-44f8-9154-5a25cbbc1865/return-options/

Example response (trimmed)

{
  "return_options": [
    {
      "id": 123,
      "option_code": "dhl-germany",
      "name": "DHL",
      "title": "DHL",
      "description": "Drop-off in parcel shop",
      "is_pickup": false,
      "is_free_label": true
    }
  ]
}

5) Apply Return Option (generates label + packing slip)

Apply one or more selected return options. This is the step that creates return labels/documents for the registration.

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

Operation: returns_return_registrations_return_options_create

View full documentation for "Apply Return Option"

Result: ReturnOptionResponse with generated label documents

Example request

{
  "options_selected": [
    {
      "id": 123
    }
  ]
}

Example response (trimmed)

{
  "labels": [
    {
      "courier": "dhl-germany",
      "tracking_number": "JVGL0123456789",
      "label": [
        {
          "url": "https://…/label.pdf",
          "content_type": "application/pdf",
          "type": ["label"]
        }
      ]
    }
  ]
}

6) Submit Return Registration

Finalize the return registration when all required selections and labels are in place. With commit: true, this triggers downstream submission behavior.

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

Operation: returns_return_registrations_submit_create

View full documentation for "Submit Return Registration"

Result: ReturnRegistration in submitted state (or unchanged if submission is skipped by flags)

Example request

{
  "commit": true
}

Example response (trimmed)

{
  "external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
  "reference": "O-123123",
  "status": "submitted",
  "articles_return": [
    {
      "line_item_id": "LI-1",
      "return_quantity": 1,
      "return_reason": "too_small"
    }
  ],
  "return_labels": [
    {
      "courier": "dhl-germany",
      "tracking_number": "JVGL0123456789"
    }
  ]
}

7) Optional: Mutate Return Registration

Use mutate operations for follow-up actions like adding a label, updating items, closing, or canceling after registration creation.

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

Operation: returns_return_registrations_mutate_create

View full documentation for "Mutate Return Registration"

Result: updated ReturnRegistration plus mutation execution results in mutations

Example request

{
  "mutations": [
    {
      "type": "add_label",
      "request": {
        "type": "shipping",
        "courier": "dhl-germany"
      }
    }
  ]
}

Example response (trimmed)

{
  "external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
  "status": "created",
  "mutations": [
    {
      "type": "add_label",
      "result": {
        "success": true,
        "message": "Mutation completed",
        "errors": {}
      }
    }
  ]
}

7a) Optional: Close a Return After Warehouse or Store Receipt

Use close_return when a submitted return has been received and 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.

For the full close request, tracking-number lookup, and batch receive-status examples, see Process Return Mutations.

8) Optional: Retrieve or validate exchange product options

If your return flow supports exchanges, use this endpoint to retrieve available variant options and validate partial exchange selections for selected line items.

Endpoint: POST /v4/returns/return-registrations/{external_id}/exchange-product-options/

Operation: returns_return_registrations_exchange_product_options_create

View full documentation for "Retrieve or validate exchange product options"

Result: map of line_item_id to exchange variant options and availability

Example request

{
  "articles_return": [
    {
      "line_item_id": "LI-1",
      "selected": true,
      "return_quantity": 1,
      "exchange_product_options": {
        "color": "Blue"
      }
    }
  ]
}

Example response (trimmed)

{
  "LI-1": {
    "size": [
      {
        "name": "S",
        "is_available": false
      },
      {
        "name": "M",
        "is_available": true
      }
    ],
    "color": [
      {
        "name": "Blue",
        "is_available": true
      },
      {
        "name": "Black",
        "is_available": true
      }
    ]
  }
}