> 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/2026-05/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) and assign the store's [stock location](#stock-availability). You can optionally define a custom alphanumeric (case-sensitive) `code` for your stores, provided that it's unique across the environment (it can contain underscores 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 [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 %} ## Payment settings By default, a store inherits the [payment settings](/core-api-reference/2026-05/payment_settings.md) available to its associated [market](/core-api-reference/2026-05/markets.md#payment-settings). You can give a store its own `payment_setting_ids` — whether these are merged with the market's or replace them entirely is controlled by `union_payment_settings`: * `union_payment_settings: false` (default) — the store's payment settings **replace** the market's. * `union_payment_settings: true` — the store's payment settings are **merged** with the market's. {% hint style="info" %} Unlike on the market, an empty `payment_setting_ids` on a store isn't an opt-out — it just means the store falls back to the market's payment settings. {% endhint %} {% hint style="warning" %} A store can't have both a list of payment setting IDs and one or more legacy ([deprecated](/core-api-reference/2026-05/readme.md#whats-deprecated) after version `2017-08`) payment methods at once — whichever one you associate first ties the store to that version's payments workflow, and associating the other one afterward returns an error. {% 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's stock locations hierarchy is extended by adding the store's stock location as the one with the highest priority and increasing the [inventory model](/core-api-reference/2026-05/inventory_models.md)'s `stock_locations_cutoff` value by 1. * If the store's stock location already belongs to the associated market's inventory model, the store's stock location priority in the market's 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 only each store's individual stock). * 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 items from your store 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 %} ## Shipments [Shipments](/core-api-reference/2026-05/shipments.md) associated with orders belonging to a store are created as usual and honor the selected [inventory strategies](/core-api-reference/2026-05/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 automatically considered dispatched to the customer directly from the store operator, meaning that: * They don't need to be associated with any shipping method. * They are marked as `delivered` as soon as the related order is placed. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.commercelayer.io/core-api-reference/2026-05/stores.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.