Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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 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 is computed taking into consideration the store's stock location (if any) first.

  • The shipments management for items available in store is simplified.

Payment settings

By default, a store inherits the payment settings available to its associated market. 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.

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.

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'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.

Shipments

Shipments associated with orders belonging to a store are created as usual and honor the selected 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.

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.

Last updated