> 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/partially-update-an-easy-return-shipping-company.md).

# Partially update an easy return shipping company

Updates one or more fields of an easy return shipping company. Only the fields included in the request body are changed.

The uniqueness check still runs: the carrier and rules the record ends up with must not match another record. Sending only `rules` therefore checks the new rules against the stored carrier, and sending only `shipping_company` checks the new carrier against the stored rules.

```json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Easy Return Shipping Companies","description":"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.\n\nWhen 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.\n\n## Core Capabilities\n\n**1. Listing & Filtering**\n* Retrieve a paginated list of easy return shipping companies.\n* 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.\n* Order results by any of the fields listed under **Sorting** using the `sort` parameter.\n\n**2. Full CRUD**\n* Register a carrier with its credentials, return-code prefix, code validity window, and collection rules.\n* Fully or partially update an existing record.\n* 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.\n\n**3. Uniqueness**\n* 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.\n* 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.\n\n## Supported Carriers\n\nThe `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.\n\nOnly the carriers below have a return-collection integration.\n\n> **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.\n\n| Value | Carrier |\n|-------|---------|\n| `aras` | Aras Kargo |\n| `droplight` | DropLight |\n| `extension` | Extension Cargo |\n| `giz` | Giz |\n| `gls` | GLS Logistic |\n| `horoz` | Horoz |\n| `k_sende` | Kargom Sende |\n| `mng` | MNG Kargo |\n| `mylerz` | Mylerz Cargo |\n| `ptt` | Ptt |\n| `ups` | UPS |\n| `yurtici` | Yurtiçi Kargo |\n\n## Collection Rules\n\nThe `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.\n\nThe `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.\n\n| Key | Type | Effect |\n|-----|------|--------|\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n\nThe 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.\n\n## Code Validity Window\n\nEvery return code carries a start and an end date, both derived from the moment the code is issued:\n\n| Field | Unit | Default | Meaning |\n|-------|------|---------|---------|\n| `start_date_gap` | days | `0` | How long after the code is issued the collection window opens. `0` means the code is valid immediately. |\n| `duration` | days | `14` | How long the collection window stays open, counted from its start. |\n\nAs with the collection rules, a carrier integration may apply these two values differently for its own return codes.\n\n## Sorting\n\nThe `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.\n\n## Dynamic Settings & Environment Variables\n\nThe 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.\n\n| Key | Type | Default | Effect |\n|-----|------|---------|--------|\n| `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. |\n\n**Environment variables:** No environment variables are read by these endpoints."}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/v1/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"schemas":{"EasyReturnShippingCompanyPatchRequest":{"type":"object","description":"Request body for partially updating an easy return shipping company. Send only the fields you want to change; every field is optional and omitted fields keep their stored values.\n\nThe length limits on `prefix` and `name` are applied when the record is stored rather than during request validation, so a longer value prevents the record from being saved.","properties":{"shipping_company":{"type":"string","description":"Carrier code, sent in lower case. Codes are case-sensitive."},"auth":{"type":"object","description":"Credentials and connection details for the carrier.","additionalProperties":true},"prefix":{"type":"string","maxLength":6,"description":"Prefix added to the return codes issued for this carrier. May be an empty string."},"rules":{"$ref":"#/components/schemas/EasyReturnCollectionRules"},"name":{"type":"string","maxLength":128,"description":"Name used to tell records of the same carrier apart. May be an empty string."},"is_active":{"type":"boolean","description":"Whether the carrier is offered for return collection."},"start_date_gap":{"type":"integer","description":"Number of days after a return code is issued before its collection window opens."},"duration":{"type":"integer","description":"Number of days the collection window stays open."}}},"EasyReturnCollectionRules":{"type":"object","description":"Rules that decide which returned items the carrier accepts and how those items are grouped into collection packages. All keys are optional and the object is stored exactly as sent, so a carrier integration may read further keys of its own. See the **Collection Rules** section for the full description of each key.","properties":{"package_rule":{"type":"string","description":"How returned items are grouped into packages. `product` groups by the product rule and is used when the key is absent; `country` groups by the country rule. Any other value means no packages are produced when several items are returned together."},"product":{"type":"object","description":"Product rule. `field_key` names the product field or attribute the rule reads, and `field_values` is a list of value groups; each group is a list of accepted values, and items whose product value falls in the same group are collected together.","properties":{"field_key":{"type":"string","description":"The product field or attribute the rule reads."},"field_values":{"type":"array","description":"Groups of accepted values. Each group is collected as one package.","items":{"type":"array","items":{"type":"string"}}}}},"country":{"type":"object","description":"Country rule. `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.","properties":{"field_key":{"type":"string","description":"The country field the rule reads."},"field_values":{"type":"array","description":"Accepted country values.","items":{"type":"string"}}}},"max_count":{"type":"integer","description":"Maximum number of items a single return code may cover. When absent or `0`, the number of items in the package is used."}},"additionalProperties":true},"EasyReturnShippingCompany":{"type":"object","description":"An easy return shipping company returned by the API.","properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique identifier of the easy return shipping company."},"shipping_company":{"allOf":[{"$ref":"#/components/schemas/EasyReturnShippingCompanyCarrierDetail"}],"description":"The carrier that collects the returned items. See the **Supported Carriers** section."},"auth":{"type":"object","description":"Credentials and connection details used to reach the carrier. The keys are defined by the carrier integration, so consult the documentation of the carrier you are registering. The object is stored exactly as sent and is returned in full by this endpoint.","additionalProperties":true},"is_active":{"type":"boolean","description":"Whether the carrier is offered for return collection. Deactivated records are retained and still listed.","default":true},"start_date_gap":{"type":"integer","description":"Number of days after a return code is issued before its collection window opens. `0` means the code is valid immediately.","default":0},"duration":{"type":"integer","description":"Number of days the collection window stays open, counted from its start.","default":14},"prefix":{"type":"string","maxLength":6,"description":"Prefix added to the return codes issued for this carrier. May be an empty string."},"rules":{"$ref":"#/components/schemas/EasyReturnCollectionRules"},"name":{"type":["string","null"],"maxLength":128,"description":"Name used to tell records of the same carrier apart. May be an empty string."}},"required":["pk","shipping_company","auth","is_active","start_date_gap","duration","prefix","rules","name"]},"EasyReturnShippingCompanyCarrierDetail":{"type":"object","description":"Read representation of a carrier — includes the carrier code and its human-readable label.","properties":{"value":{"type":"string","description":"Carrier code."},"label":{"type":"string","description":"Human-readable name of the carrier."}},"required":["value","label"]},"ValidationError":{"type":"object","description":"Returned when the request contains invalid or missing data. Errors are grouped by the field they apply to: each key is the name of a field from the request and its value is a list of one or more messages describing what is wrong with that field. Messages that do not belong to any single field are grouped under `non_field_errors`.","properties":{"non_field_errors":{"type":"array","description":"Error messages that apply to the request as a whole rather than to a specific field.","items":{"type":"string"}}},"additionalProperties":{"type":"array","description":"The list of error messages for the field named by the key.","items":{"type":"string"}}},"EasyReturnShippingCompanyBusinessError":{"type":"array","description":"Returned when the carrier and rules the request would produce already belong to another record. The body is a list holding a single message.","items":{"type":"string"}},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true}},"responses":{"EasyReturnShippingCompanyValidationOrBusinessError":{"description":"The request contains invalid or missing data, or the carrier and rules it would produce already belong to another record.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/EasyReturnShippingCompanyBusinessError"}]}}}},"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated user does not have administrator privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"EasyReturnShippingCompanyNotFound":{"description":"The requested easy return shipping company does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/easy_return_shipping_companies/{id}/":{"patch":{"tags":["Easy Return Shipping Companies"],"operationId":"partialUpdateEasyReturnShippingCompany","summary":"Partially update an easy return shipping company","description":"Updates one or more fields of an easy return shipping company. Only the fields included in the request body are changed.\n\nThe uniqueness check still runs: the carrier and rules the record ends up with must not match another record. Sending only `rules` therefore checks the new rules against the stored carrier, and sending only `shipping_company` checks the new carrier against the stored rules.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EasyReturnShippingCompanyPatchRequest"}}}},"responses":{"200":{"description":"The updated easy return shipping company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EasyReturnShippingCompany"}}}},"400":{"$ref":"#/components/responses/EasyReturnShippingCompanyValidationOrBusinessError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/EasyReturnShippingCompanyNotFound"}}}}}}
```


---

# 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/partially-update-an-easy-return-shipping-company.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.
