> 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/districts.md).

# Districts

Administrative endpoints for **districts** — the smallest administrative subdivision in the address hierarchy, filed under a township within a city. Districts refine an address below the township level (neighbourhood/quarter) and can carry their own post code.

A district consists of a display name, the city and township it belongs to, an active/inactive status, an optional post code, and optional multilingual translations of the name. The country is not stored on the district directly; it is reached through the township's city.

### Core Capabilities

**1. District Listing & Filtering**

* Retrieve a paginated list of all districts (active and inactive), ordered by name ascending.
* Filter by `name`, `city`, or `township`, restrict to districts that have a retail store with `has_retail_store=true`, or pass a bare `township` identifier.
* Order results with the `sort` parameter.

**2. District Lifecycle Management**

* Create a district under a city and township.
* Fully or partially update an existing district.
* Deactivate a district (soft delete — sets `is_active` to `false`; the record is not removed).

**3. Multilingual Names**

* Store translated names under the `translations` field, keyed by language code.

### District Fields

| Field          | Type                             | Description                                                                                                                 |
| -------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `pk`           | integer                          | The unique identifier of the district. Assigned by the server; read-only.                                                   |
| `is_active`    | boolean                          | Whether the district is active. Defaults to `true`. Inactive districts are excluded from storefront address lookups.        |
| `name`         | string (max 128 chars)           | The official name of the district. Required on create and full update.                                                      |
| `city`         | integer                          | The identifier of the city this district belongs to. Required on create and full update.                                    |
| `township`     | integer                          | The identifier of the township this district belongs to. Required on create and full update.                                |
| `postcode`     | string (max 255 chars) or `null` | The post/zip code of the district. Optional.                                                                                |
| `translations` | object or `null`                 | A mapping of language codes to translated field values. Example: `{"tr": {"name": "Kadıköy"}}`. Optional; defaults to `{}`. |

The combination (`city`, `township`, `name`) must be **unique**. A duplicate is rejected with `406 Not Acceptable` carrying `error_code` `address_100_6`.

### Filtering & Ordering

| Parameter          | Match            | Notes                                                                                                     |
| ------------------ | ---------------- | --------------------------------------------------------------------------------------------------------- |
| `name`             | Exact            | Filter by district name.                                                                                  |
| `city`             | Exact            | Keep only districts in the given city identifier.                                                         |
| `township`         | Exact            | Keep only districts in the given township identifier. Also accepted as a bare numeric `?township=` value. |
| `has_retail_store` | Boolean (`true`) | When `true`, keep only districts that have at least one retail store.                                     |

Results are ordered by `name` ascending by default. Use the `sort` query parameter to change the order; prefix with `-` for descending.

### Soft Delete

Calling `DELETE /districts/{id}/` does **not** remove the record from the database. It sets `is_active` to `false`, which hides the district from storefront address forms. The record can be reactivated at any time with `PATCH /districts/{id}/` sending `{"is_active": true}`.

### Dynamic Settings & Environment Variables

No dynamic settings (`dj_dynamic_settings`) affect the district endpoints. In particular, `DEFAULT_COUNTRY_CODE` and `ADDRESS_DISTRICT_REQUIRED` — both registered in `omnishop/address/settings/conf.py` — do not change the behaviour of these endpoints: `ADDRESS_DISTRICT_REQUIRED` only controls whether a district is mandatory in the address forms, and `DEFAULT_COUNTRY_CODE` is consumed by the address and checkout services. **Environment variables:** none 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/districts.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.
