> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/stores.md).

# Stores

The store object and the allowed CRUD operations on the related resource endpoint

The store resource enables you to map a market's physical shops (e.g. retail stores, pop-up stores, etc.) to effectively manage in-store sales and more. To create a store you have to give it a name and set the market it belongs to. If needed, you can specify a different merchant (otherwise it will be inherited from the associated market), assign the store's [stock location](#stock-availability), and enable store-specific [payment methods](#available-payment-methods).

You can optionally define a custom alphanumeric (case-sensitive) `code` for your stores, provided that it's unique across the environment (it can contain underscore and hyphens, spaces are not allowed , the maximum length is **25** characters).

A store can be [put in scope](/core/authentication.md#putting-a-store-in-scope) when requesting an access token so that:

* All the fetched resources (e.g. SKUs, prices) are automatically filtered by the market the store is associated with.
* Orders created with a specific store in scope belong to both the store and the associated market.
* The [stock availability](#stock-availability) is computed taking into consideration the store's stock location (if any) first.
* The [available payment methods](#available-payment-methods) are updated accordingly.
* The [shipments management](#shipments) for items available in store is simplified.

{% hint style="danger" %}
Stores are a **beta** feature, still open for improvements and refinements. We encourage you to try it out and share any feedback that could help us enhance its fit for your use cases.
{% endhint %}

## Stock availability

The stock availability with a store in scope is calculated according to the following logic:

* If the store has a stock location and the associated market has an inventory model with different stock locations, the market stock locations hierarchy is extended by adding the store's stock location as the one with the highest priority and increasing by 1 the [inventory model](/core-api-reference/inventory_models.md)'s `stock_locations_cutoff` value.
* If the store's stock location already belongs to the associated market's inventory model, the store's stock location priority in the market inventory model is updated (set to 0 — i.e. the highest), without increasing the cutoff.
* If the associated market has an empty inventory model (i.e. with no stock location defined), only the store's stock location is considered (e.g. you can create a market that contains all of your brand's stores and decide to sell using the single stores' stock only).
* If the store has no stock location, the associated market's stock location hierarchy (as defined in the related inventory model) is used as a fallback.

{% hint style="success" %}
This logic enables you to sell from your store items that are not physically in-store leveraging the inventory model of the associated market, thus making [endless aisle](https://www.eicom.org/ecommerce-wiki/endless-aisle) possible.
{% endhint %}

## Available payment methods

The available [payment methods](/core-api-reference/payment_methods.md) with a store in scope are returned according to the following logic:

* If the store has one or more specific payment methods enabled, the returned available payment methods are the store's only.
* If the store has no specific payment method enabled, the returned available payment methods are the associated market's ones.

## Shipments

[Shipments](/core-api-reference/shipments.md) associated with orders belonging to a store are created as usual and honor the selected [inventory strategies](/core-api-reference/inventory_models.md#inventory-strategies) (taking into consideration the new stock location hierarchy due to the addition of the store's stock location, if any).

Shipments that don't involve stock transfers from other stock locations of the associated market and that have only stock items belonging to the store's stock location are handled directly by the store itself. How they evolve from there is determined by the store's `shipment_policy`:

* `auto_delivered` (default) — they are considered dispatched to the customer directly from the store operator, meaning that they don't need to be associated with any shipping method and are marked as `delivered` as soon as the related order is placed.
* `standard` — they follow the regular shipment lifecycle and require a shipping method like any other shipment. Use it for stores that run a backoffice with a dedicated picking and packing station, whose operators need a work queue and the shipment events that come with it.

Every other shipment of a store's order keeps following the regular shipment lifecycle, regardless of the policy value.

{% hint style="info" %}
The policy is always resolved from the order's store (and not from the store that is currently in scope), so that all the shipments of the same order behave consistently — including the ones created manually after the order approval. Each shipment exposes the resolved value in its read-only `store_shipment_policy` attribute.
{% endhint %}

{% hint style="warning" %}
When the `standard` shipment policy is selected, the order cannot be placed until the shipment is associated with a shipping method. Make sure the store's market defines a `default_shipping_method` or that your sales channel selects one explicitly, otherwise the in-store checkout will fail.
{% endhint %}

<details>

<summary>Data model</summary>

Check the related [ER diagram](/data-model/pricing-and-markets/stores.md) and explore the flowchart that illustrates how the store resource relates to the other API entities.

</details>


---

# 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://docs.commercelayer.io/core-api-reference/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.