# Headless Returns Flow

#### 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`

<a href="https://api.parcellab.com/v4/docs/#tag/Return-Registration/operation/returns_return_registrations_lookup_order_create" class="button secondary" data-icon="file-lines">View full documentation for "Create Return Registration (from order)"</a>

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

<details>

<summary>Example request</summary>

```json
{
  "account": 161912,
  "code": "de-de",
  "identifier": {
    "reference": "O-123123",
    "identifier": "user@example.com"
  }
}
```

</details>

<details>

<summary>Example response (trimmed)</summary>

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

</details>

#### 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`

<a href="https://api.parcellab.com/v4/docs/#tag/Return-Registration/operation/returns_return_registrations_create" class="button secondary" data-icon="file-lines">View full documentation for "Register Return"</a>

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

<details>

<summary>Example request</summary>

```json
{
  "account": 161912,
  "code": "de-de",
  "reference": "O-123123",
  "customer_email": "user@example.com",
  "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
    }
  ]
}
```

</details>

<details>

<summary>Example response (trimmed)</summary>

```json
{
  "external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
  "reference": "O-123123",
  "status": "created",
  "customer_email": "user@example.com",
  "articles_order": [
    {
      "line_item_id": "LI-1",
      "article_name": "T-Shirt",
      "quantity": 1
    }
  ]
}
```

</details>

#### 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`

<a href="https://api.parcellab.com/v4/docs/#tag/Return-Registration/operation/returns_return_registrations_article_info_retrieve" class="button secondary" data-icon="file-lines">View full documentation for "Retrieve Article Info"</a>

Result: `ReturnRegistrationReturnability` with returnability rules and current selection state

<details>

<summary>Example request</summary>

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

</details>

<details>

<summary>Example response (trimmed)</summary>

```json
{
  "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
}
```

</details>

#### 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`

<a href="https://api.parcellab.com/v4/docs/#tag/Return-Registration/operation/returns_return_registrations_article_info_partial_update" class="button secondary" data-icon="file-lines">View full documentation for "Validate Article Info (Return items)"</a>

Result: updated `ReturnRegistrationReturnability`, including the selection state you submitted

<details>

<summary>Example request</summary>

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

</details>

<details>

<summary>Example response (trimmed)</summary>

```json
{
  "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
}
```

</details>

#### 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`

<a href="https://api.parcellab.com/v4/docs/#tag/Return-Registration/operation/returns_return_registrations_return_options_retrieve" class="button secondary" data-icon="file-lines">View full documentation for "Retrieve Return Options"</a>

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

<details>

<summary>Example request</summary>

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

</details>

<details>

<summary>Example response (trimmed)</summary>

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

</details>

#### 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`

<a href="https://api.parcellab.com/v4/docs/#tag/Return-Registration/operation/returns_return_registrations_return_options_create" class="button secondary" data-icon="file-lines">View full documentation for "Apply Return Option"</a>

Result: `ReturnOptionResponse` with generated label documents

<details>

<summary>Example request</summary>

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

</details>

<details>

<summary>Example response (trimmed)</summary>

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

</details>

#### 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`

<a href="https://api.parcellab.com/v4/docs/#tag/Return-Registration/operation/returns_return_registrations_submit_create" class="button secondary" data-icon="file-lines">View full documentation for "Submit Return Registration"</a>

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

<details>

<summary>Example request</summary>

```json
{
  "commit": true
}
```

</details>

<details>

<summary>Example response (trimmed)</summary>

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

</details>

#### 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`

<a href="https://api.parcellab.com/v4/docs/#tag/Return-Registration/operation/returns_return_registrations_mutate_create" class="button secondary" data-icon="file-lines">View full documentation for "Mutate Return Registration"</a>

Result: updated `ReturnRegistration` plus mutation execution results in `mutations`

<details>

<summary>Example request</summary>

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

</details>

<details>

<summary>Example response (trimmed)</summary>

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

</details>

#### 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`

<a href="https://api.parcellab.com/v4/docs/#tag/Return-Registration/operation/returns_return_registrations_exchange_product_options_create" class="button secondary" data-icon="file-lines">View full documentation for "Retrieve or validate exchange product options"</a>

Result: map of `line_item_id` to exchange variant options and availability

<details>

<summary>Example request</summary>

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

</details>

<details>

<summary>Example response (trimmed)</summary>

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

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.parcellab.com/docs/developers/returns/headless-returns-flow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.