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

# Easy Return Shipping Companies

Administrative endpoints for **easy return shipping companies** — the carriers that collect returned items from the customer. Each record binds one carrier to the credentials used to reach it, the rules that decide which returned items that carrier may collect, and the validity window of the return code it issues.

When a customer starts a return, the platform goes through the active records and matches the rules stored on each one against the items being returned. The first carrier whose rules accept the items issues the return code. A carrier that is not active is never considered.

### Core Capabilities

**1. Listing & Filtering**

* Retrieve a paginated list of easy return shipping companies.
* Filter by carrier, name, return-code prefix, active status, collection window values, and creation and modification dates. The credential and rule objects cannot be filtered on.
* Order results by any of the fields listed under **Sorting** using the `sort` parameter.

**2. Full CRUD**

* Register a carrier with its credentials, return-code prefix, code validity window, and collection rules.
* Fully or partially update an existing record.
* Deactivate a record: `DELETE` performs a **soft delete** — it sets `is_active` to `false` and retains the record. Permanent removal is not available through this API.

**3. Uniqueness**

* The same carrier may be registered several times with different rules, so that different product groups or destination countries are collected under different credentials or code prefixes.
* Two records may never share both the same carrier and the same rules. A create or update that would produce such a pair is rejected with `Easy return shipping company already exists.` The comparison is made on the complete rule object, so changing a single rule value is enough to make a record distinct.

### Supported Carriers

The `shipping_company` field accepts any carrier code known to the platform. Send the lower-case code (for example `ups`) on create and update; codes are case-sensitive. On retrieval the field is returned as an object with `value` and `label` keys.

Only the carriers below have a return-collection integration.

> **Warning:** A record can be saved with any other carrier code, but such a record must be left inactive. When a return is processed, every active record is asked for a return code, and a carrier without a return-collection integration cannot produce one — so a single active record of that kind stops returns from being processed for all carriers, not only for itself. Keep `is_active` set to `false` on any record whose carrier is not listed below.

| Value       | Carrier         |
| ----------- | --------------- |
| `aras`      | Aras Kargo      |
| `droplight` | DropLight       |
| `extension` | Extension Cargo |
| `giz`       | Giz             |
| `gls`       | GLS Logistic    |
| `horoz`     | Horoz           |
| `k_sende`   | Kargom Sende    |
| `mng`       | MNG Kargo       |
| `mylerz`    | Mylerz Cargo    |
| `ptt`       | Ptt             |
| `ups`       | UPS             |
| `yurtici`   | Yurtiçi Kargo   |

### Collection Rules

The `rules` object decides which returned items a carrier accepts and how those items are grouped into collection packages. All keys are optional; the object is stored exactly as sent.

The `product` and `country` keys decide whether the carrier may collect the items at all. The `package_rule` and `max_count` keys apply when several returned items are collected together in one package.

| Key            | Type                               | Effect                                                                                                                                                                                                                                                                                                                                                |
| -------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `package_rule` | string                             | Selects how returned items are grouped into packages: `product` (the default when the key is absent) groups by the product rule, `country` groups by the country rule. Any other value means no packages are produced when several items are returned together.                                                                                       |
| `product`      | object `{field_key, field_values}` | `field_key` names the product field or attribute the rule reads. `field_values` is a list of value groups; each group is itself a list of accepted values. Items whose product value falls in the same group are collected together. When this key is absent, the carrier accepts nothing under the `product` grouping.                               |
| `country`      | object `{field_key, field_values}` | `field_key` names the field read from the delivery address country, and `field_values` lists the accepted values. Items are accepted only when the country value of the returning order is in the list. When this key is absent, no country restriction is applied to eligibility, and the carrier produces no packages under the `country` grouping. |
| `max_count`    | integer                            | Maximum number of items a single return code may cover. When absent or `0`, the number of items in the package is used.                                                                                                                                                                                                                               |

The keys above are the ones the shared return logic reads. A carrier integration may read further keys of its own from `rules` and from `auth`, and may apply the values above differently, so the integration documentation of the carrier you are registering is authoritative for its own behaviour.

### Code Validity Window

Every return code carries a start and an end date, both derived from the moment the code is issued:

| Field            | Unit | Default | Meaning                                                                                                 |
| ---------------- | ---- | ------- | ------------------------------------------------------------------------------------------------------- |
| `start_date_gap` | days | `0`     | How long after the code is issued the collection window opens. `0` means the code is valid immediately. |
| `duration`       | days | `14`    | How long the collection window stays open, counted from its start.                                      |

As with the collection rules, a carrier integration may apply these two values differently for its own return codes.

### Sorting

The `sort` parameter accepts `pk`, `shipping_company`, `name`, `prefix`, `is_active`, `start_date_gap`, `duration`, `auth`, and `rules`. Prefix a field with a hyphen for descending order. Sorting by `auth` or `rules` is accepted but orders records by the raw content of those objects, which rarely produces a useful order. The creation and modification dates can be filtered but not sorted on.

### Dynamic Settings & Environment Variables

The following dynamic setting does not change the behaviour of the administrative endpoints described here — every action stays available and behaves identically regardless of its value. It determines how the records managed here are **used** when a customer returns an item.

| Key                            | Type                                | Default                                                           | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------ | ----------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EASY_RETURN_PACKAGE_STRATEGY` | string (choice of two fixed values) | `"omnishop.orders.strategies.RuleBasedEasyReturnPackageStrategy"` | Selects who chooses the return carrier. With the default value the carrier is chosen automatically: the platform walks through the active records and picks the first whose `rules` accept the returned items, so the `rules` object is what drives the outcome. With `"omnishop.orders.strategies.SelectionBasedEasyReturnPackageStrategy"` the customer chooses the carrier from the active records, and the pickup-appointment flow becomes available; `rules` is then no longer used to select the carrier, though the remaining fields still apply to the code that is issued. |

**Environment variables:** No environment variables are read by these endpoints.


---

# 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://apidocs.akinon.com/commerce-openapis/admin/easy-return-shipping-companies.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.
