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

# Retail Stores

Administrative endpoints for **retail stores** — physical brick-and-mortar stores that act as fulfilment nodes in omnichannel flows. A retail store is geolocated (`latitude`/`longitude`), placed in the address hierarchy through its `township` (which resolves to a city and country) and an optional `district`, and carries operational flags such as click-and-collect, in-store return, and fast delivery.

This is the admin management API over these records — it returns the full table, including inactive stores. The storefront-facing store-locator endpoints are separate.

### Core Capabilities

**1. Listing, Filtering & Store Locator**

* Retrieve the list of retail stores. The list is returned with related objects (township, city, country, district) expanded, ordered by `sort_order`, then city, township, and store name.
* Filter by location (`country`, `city`, `township`, `district`), `name`, `click_and_collect`, or `store_type`.
* Find the stores nearest to a point, or the stores within a radius, with the geo query parameters (see **Store Locator**).

**2. Store Lifecycle Management**

* Create a store.
* Retrieve a single store.
* Fully update a store with `PUT`. **Partial update (`PATCH`) is not supported** (`405 Method Not Allowed`).
* Delete a store (see **Deleting a Retail Store**).

### Retail Store Fields

| Field                   | Type                       | Description                                                                                                                                           |
| ----------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pk`                    | integer                    | The unique identifier of the store. Read-only.                                                                                                        |
| `name`                  | string (max 255)           | The store name. Required. Unique together with `township` and `store_type`.                                                                           |
| `township`              | integer                    | The identifier of the township the store is in. Required. In list responses this is expanded to an object (township → city → country).                |
| `district`              | integer or `null`          | The identifier of the district the store is in. Optional. Expanded in list responses.                                                                 |
| `address`               | string                     | The street address. Required.                                                                                                                         |
| `phone_number`          | string (max 128)           | The store phone number. Required.                                                                                                                     |
| `fax_phone_number`      | string (max 128) or `null` | The store fax number. Optional.                                                                                                                       |
| `image`                 | string (uri) or `null`     | The store image. Optional. Upload with a `multipart/form-data` request, or set `image_path` to reference an already-uploaded file.                    |
| `image_path`            | string or `null`           | Write-only helper — the storage path of an already-uploaded image, used instead of uploading a file.                                                  |
| `store_hours`           | array or `null`            | Weekly opening hours: a list of up to 7 entries, each a two-element `[open, close]` pair of `HH:MM:SS` times (either may be `null` for a closed day). |
| `latitude`              | string (decimal) or `null` | Latitude, up to 11 digits with 8 decimal places. Used by the store locator.                                                                           |
| `longitude`             | string (decimal) or `null` | Longitude, up to 11 digits with 8 decimal places. Used by the store locator.                                                                          |
| `is_active`             | boolean                    | Whether the store is active. Defaults to `true`.                                                                                                      |
| `click_and_collect`     | boolean                    | Whether the store supports click-and-collect pickup. Defaults to `false`.                                                                             |
| `store_type`            | integer or `null`          | The identifier of the store type. Optional. Part of the uniqueness constraint with `name` and `township`.                                             |
| `kapida_enabled`        | boolean                    | Whether ship-from-store / at-door fulfilment is enabled. Defaults to `false`.                                                                         |
| `fast_delivery`         | boolean                    | Whether the store supports fast delivery. Defaults to `false`.                                                                                        |
| `config`                | object                     | Free-form JSON configuration. Defaults to an empty object.                                                                                            |
| `group`                 | integer or `null`          | The identifier of the store group this store belongs to. Optional.                                                                                    |
| `sort_order`            | integer or `null`          | The primary ordering key for listings. Optional.                                                                                                      |
| `erp_code`              | string (max 128) or `null` | The store's ERP code, used for store-level stock lookups.                                                                                             |
| `translations`          | object                     | Translations of the translatable fields (`name`), keyed by language code. Defaults to an empty object.                                                |
| `related_retail_stores` | array of integer           | Read-only list of the identifiers of linked stores.                                                                                                   |
| `absolute_url`          | string                     | Read-only. Present in list responses only — the storefront URL of the store.                                                                          |
| `created_date`          | string (date-time)         | Read-only. When the store was created.                                                                                                                |
| `modified_date`         | string (date-time)         | Read-only. When the store was last modified.                                                                                                          |

### Store Locator

The list endpoint supports nearest-store and radius queries through query parameters. Distance search activates only when `latitude`, `longitude`, `radius`, and `quantity` are all supplied.

| Parameter   | Type    | Effect                                                                                        |
| ----------- | ------- | --------------------------------------------------------------------------------------------- |
| `latitude`  | number  | The reference point latitude.                                                                 |
| `longitude` | number  | The reference point longitude.                                                                |
| `radius`    | number  | The search radius. When `nearest` is not truthy, only stores within this radius are returned. |
| `quantity`  | integer | The maximum number of stores to return.                                                       |
| `nearest`   | boolean | When truthy, returns the `quantity` closest stores ordered by distance, ignoring the radius.  |

### Pagination

This endpoint returns **all** matching stores in a single page; the `page` and `limit` parameters are accepted for envelope consistency but do not paginate the result. The response keeps the standard `{count, next, previous, results}` shape, with `next` and `previous` always `null`.

### Deleting a Retail Store

> **Important:** `DELETE /retailstores/{id}/` is a **hard delete** — the record is removed from the database. A store that is still referenced by other records (for example order or shipping addresses) is protected and cannot be deleted; detach those references first.

### Filtering & Ordering

| Parameter           | Match                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| `country`           | Stores whose (active) country has the given identifier.                                           |
| `city`              | Stores whose (active) city has the given identifier.                                              |
| `township`          | Stores in the given (active) township.                                                            |
| `district`          | Stores in the given (active) district.                                                            |
| `name`              | Exact match on the store name.                                                                    |
| `click_and_collect` | Boolean click-and-collect flag.                                                                   |
| `store_type`        | The store type by identifier, with nested `store_type__name` / `store_type__label` exact matches. |

Results are ordered by `sort_order`, then city name, township name, and store name. Use the `sort` parameter to override the order; prefix a field with a hyphen for descending order.

### Dynamic Settings & Environment Variables

No dynamic settings (`dj_dynamic_settings`) are read by these endpoints, and no environment variables are read directly. The store-locator behaviour is driven entirely by the request query parameters described above.


---

# 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/retail-stores.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.
