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.

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? documentation.

1. Overview

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

---

2. Code Generation

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

2.1. Codes Generated by Commerce

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.

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.

2.2. Codes Supplied by the Carrier

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

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.

2.3. Codes Are Not Deterministic

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.

---

3. Uniqueness Scope

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.

---

4. Opening a Second Return Request for the Same Order

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.

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.

---

5. Validity Period and Cancellation

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.

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.

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.

---

6. Carrier Selection and Packaging

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)

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.

For the accepted values of this setting, see the Dynamic Settings documentation.