> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/commerce/easy-return.md).

# Easy Return

Easy return lets a customer return delivered items with a return code instead of arranging the shipment themselves. Commerce creates the code, hands it to the carrier and shares it with the customer.

This document describes how easy return behaves in Commerce. It covers the values a return code is derived from and the scope in which uniqueness is guaranteed. It also covers how long a code stays valid and how Commerce selects the carrier that produces it.

{% hint style="info" %}
Carrier-specific easy return setup, such as authentication values, carrier parameters and per-carrier field mapping, is out of the scope of this document. For carrier configuration, refer to the [How to Manage Easy Return Shipping Options in Omnitron?](/tutorials/omnitron/sales-channels/sales-channel-settings/how-to-manage-easy-return-shipping-options-in-omnitron.md) documentation.
{% endhint %}

## <mark style="color:red;">1. Overview</mark>

Commerce creates an easy return record when a cancellation request of type **refund** is opened for an order item. The easy return shipping option that handles the return produces the code. Commerce then stores the code together with its validity period and status.

**Key Characteristics:**

* Commerce creates one record per **return package**, not per order item. Every order item in the same package shares the same code.
* Commerce creates a record at request time and never pre-allocates codes.
* The record is exposed on the cancellation request through the `easy_return` object.
* Commerce passes the code to the return SMS, e-mail and notification templates.

The `easy_return` object contains the following fields:

| Field                           | Description                                                                                                  |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `code`                          | The easy return code                                                                                         |
| `shipping_company`              | Carrier that handles the return                                                                              |
| `easy_return_shipping_provider` | The easy return shipping option that produced the code. Use it to tell two options of the same carrier apart |
| `start_date`                    | First day the code is valid                                                                                  |
| `end_date`                      | Last day the code is valid                                                                                   |
| `status`                        | Either `active` or `cancelled`                                                                               |
| `tracking_number`               | Carrier tracking number, when the carrier returns one                                                        |
| `tracking_url`                  | Carrier tracking URL, when the carrier returns one                                                           |
| `pickup_date`                   | Selected appointment slot, when appointment selection is used                                                |

***

## <mark style="color:red;">2. Code Generation</mark>

Where the code comes from depends on the carrier:

| Code produced by | Carriers                                                                                                                                                  |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Commerce         | Aras Kargo, Yurtiçi Kargo, MNG Kargo, PTT Kargo, Horoz Lojistik, GLS, Kargom Sende, Mylerz, and every carrier connected through the extension integration |
| The carrier      | UPS, DropLight, GIZ                                                                                                                                       |

### <mark style="color:red;">2.1. Codes Generated by Commerce</mark>

For the carriers listed above, Commerce builds the code itself. The code is derived from the following values:

| Source                  | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| Order number            | Number of the order the return belongs to                         |
| Order item identifiers  | Identifiers of the order items covered by the package             |
| Request timestamp       | The moment the code is requested                                  |
| Shipping Company Prefix | The prefix defined on the easy return shipping option in Omnitron |

Commerce turns these values into a short, unpredictable character sequence, places the Shipping Company Prefix in front of it and converts the result to uppercase. A shipping option with the prefix `AKN` therefore produces a code such as `AKN4F2C1B9D3`.

{% hint style="info" %}
Codes do not look the same for every carrier. Some integrations produce a longer code, some produce a digits-only code, and some add the prefix only when their configuration enables it.
{% endhint %}

### <mark style="color:red;">2.2. Codes Supplied by the Carrier</mark>

Three integrations do not build the code themselves. They ask the carrier for it and Commerce stores the returned value as it is. The carrier defines the format, so the Shipping Company Prefix and the values in the table above do not apply.

| Carrier   | What Commerce stores                                        |
| --------- | ----------------------------------------------------------- |
| UPS       | The shipment number that UPS returns for the pickup request |
| DropLight | The code that the DropLight service returns                 |
| GIZ       | The code that the GIZ service returns                       |

{% hint style="info" %}
GIZ requests a separate code for each order item in a multi-item return and stores them as a single hyphen-separated value. One return record can therefore hold several carrier codes.
{% endhint %}

### <mark style="color:red;">2.3. Codes Are Not Deterministic</mark>

The moment of the request is one of the values that shape a code Commerce generates. Requesting a code twice for the same order and the same order items therefore produces two different codes. There is no reproducible mapping between an order and its return code, and you cannot recalculate a code from order data afterwards. Carrier-supplied codes are equally unpredictable, because only the carrier decides them.

***

## <mark style="color:red;">3. Uniqueness Scope</mark>

| Scope                       | Guaranteed | Description                                                                    |
| --------------------------- | ---------- | ------------------------------------------------------------------------------ |
| Whole Commerce installation | Yes        | A code can never belong to two different return records                        |
| Return package              | Yes        | Commerce creates exactly one code per package, shared by all order items in it |
| Order                       | No         | An order may hold several codes: one per package and one per return request    |
| Customer                    | No         | Commerce applies no customer-level scoping                                     |
| Sales channel               | No         | Commerce applies no channel-level scoping; uniqueness is installation-wide     |

Because uniqueness is installation-wide, you can locate a return from its code alone. Filter the order list by easy return code to find the order that the code belongs to.

***

## <mark style="color:red;">4. Opening a Second Return Request for the Same Order</mark>

Each return request runs the code generation independently. Commerce does not look up a code that it previously created for the order. A second return request therefore produces a **new return record with a new code**. This holds even when the same order items, the same carrier and the same customer are involved.

Commerce never reuses a stored code for a new return record. When a code that Commerce already stores comes up again, Commerce rejects the request with the error code `cancellation_request_100_10`.

{% hint style="warning" %}
Two order items returned in the **same** request may share one code, because they travel in the same package. This is expected.

Two **separate** return requests on the same order always receive different codes. A repeated code is therefore not a state the system tolerates, and the second request fails. For a code that Commerce builds itself, a repeat means two requests were created at the very same instant. For a code that the carrier supplies, it means the carrier returned a code it had already issued.
{% endhint %}

***

## <mark style="color:red;">5. Validity Period and Cancellation</mark>

For most carriers Commerce derives the validity period from the easy return shipping option configured in Omnitron:

| Field        | Source         | Description                                     |
| ------------ | -------------- | ----------------------------------------------- |
| `start_date` | Start Date Gap | Request time plus the configured number of days |
| `end_date`   | Delivery Time  | `start_date` plus the configured number of days |

Commerce stores these values on the return record and forwards them to the carrier. The carrier uses them as the code expiry date of its own return shipment record. Where the integration reports it, Commerce also stores the maximum number of items the carrier accepts under the code.

{% hint style="warning" %}
Commerce does not enforce the validity period. There is no expiry job and no expired status. An expired code is rejected by the carrier, not by Commerce.

Not every integration fills these fields either. DropLight and GIZ ignore the Start Date Gap and start the validity at the moment of the request. Horoz Lojistik stores no end date, and Kargom Sende stores neither a start nor an end date. For those two carriers the return record carries no usable validity period, and only the carrier knows how long the code lives.
{% endhint %}

A return record becomes `cancelled` only when its return request is rejected. Because one record may serve several order items, Commerce cancels the code only once the last request that uses it is rejected. While another request is still open or waiting, the record stays `active`.

When Commerce cancels a code, it asks the carrier to cancel it as well. Integrations that state they offer no remote cancellation are cancelled in Commerce only, and the carrier is never told. If an integration has no cancellation support at all, or the call to the carrier fails, the rejection itself fails and nothing is cancelled.

***

## <mark style="color:red;">6. Carrier Selection and Packaging</mark>

The `EASY_RETURN_PACKAGE_STRATEGY` dynamic setting selects the carrier, not the code format. The rule-based strategy picks the first active shipping option whose product and country rules cover the item, and it is the default. The selection-based strategy lets the customer choose the shipping company and rejects the request when it is missing. Both strategies then ask the selected option for the code, so the format, the uniqueness scope and the validity period stay the same.

The setting affects code generation in one way only. It changes how Commerce groups items into packages in a multi-item return, and therefore how many codes the order receives.

| Strategy        | Grouping in a multi-item return                                         |
| --------------- | ----------------------------------------------------------------------- |
| Rule-based      | By the product and country rules of each shipping option                |
| Selection-based | By shipping company and selected appointment slot (date and hour range) |

{% hint style="info" %}
A customer who selects the same shipping company but two different appointment slots receives two codes. Appointment selection is available only with the selection-based strategy.
{% endhint %}

For the accepted values of this setting, see the [Dynamic Settings](/technical-guides/commerce/dynamic-settings.md) documentation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.akinon.com/technical-guides/commerce/easy-return.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.