# Store-scoped resources and data fencing

## Store-scoped resources

commercetools provides [Store-scoped API methods](/api/projects/stores.md#store-scoped-api-methods) for resources that support Store scoping. These endpoints manage data within a specific Store's context.

Stores are also the mechanism through which B2B buyer organizations get their commercial context. A Business Unit resolves to a Store to inherit its assortment, pricing, and order visibility. To see how this works, see [Stores and Business Units](/learning-model-b2b-commerce/model-buyer-organizations/stores-and-business-units.md) in the Model B2B commerce path.

We can visualise Stores as placing a data fence across these resources, as shown in the below image.

![Data fencing with Stores across commercetools resources](https://docs.commercetools.com/learning-model-your-business-structureimages/stores-and-channels/store-scoped-resources.svg)

## Store-scoped endpoints

Store-scoped endpoints provide a dedicated way to interact with resources within the context of a specific Store. This is crucial for maintaining data separation and ensuring that operations only affect the intended Store's data. Let's illustrate this with the Carts endpoint as an example:

**Project-scoped endpoint:**
`/carts`

This endpoint operates at the Project level. Any operations performed here can access all Carts within the entire Project, regardless of the Store they might be associated with.

**Store-scoped endpoint:**
`/in-store/key={storeKey}/carts`

This endpoint introduces the concept of Store scoping. The addition of `/in-store/key={storeKey}` to the URL path restricts the scope of the operation to a specific Store, identified by its unique `storeKey`.

### How it works

The `storeKey` acts as a filter, ensuring that only Carts belonging to the specified Store are retrieved, created, updated, or deleted. This prevents accidental modification of Carts belonging to other Stores within the same Project.

The benefits of Store scoping include:

- **Enhanced data security:** isolates data and operations within specific Stores, reducing the risk of unintended data modification or access.
- **Simplified management:** easier to manage resources within a specific Store context without needing complex filtering logic in your application code.
- **Improved performance:** by limiting the scope of queries and operations, you can potentially improve performance by reducing the amount of data processed.
- **Clearer intent:** the URL structure indicates the intended scope of the operation, improving code readability and maintainability.
- **Increased Cart Discount limit:** with Stores, you can add more [Store-specific Cart Discounts](/api/limits.md#cart-discounts).

### GraphQL integration

Stores and Channels integrate seamlessly with the GraphQL API:

- **Query fields:** `inStore` (single Store) and `inStores` (multiple Stores)
- **Mutation arguments:** `storeKey` specifies the Store for creating or updating resources.

For full syntax and examples, see [Store-scoped queries and mutations](/api/graphql.md#store-scoped-queries-and-mutations) in the GraphQL API reference.

## OAuth Scopes for Enhanced Security

OAuth scopes for `in-store` endpoints follow the format `{resource}:{projectKey}:{storeKey}`. Using the `storeKey` scope allows you to create API Clients or OAuth tokens with access limited to specific Stores. This is crucial for data fencing, isolating accessible data based on the associated Store. For the complete list of available scopes and their descriptions, see [Scopes](/api/scopes.md).

**Please note:** API clients require specific Store scopes to create tokens with those scopes. An API Client with `manage_customers:{projectKey}` cannot create a token for `manage_customers:{projectKey}:{storeKey}` unless it also has the latter scope. The non store version of the scope can still use the store version of the endpoint example: a token with `manage_customers:{projectKey}` can use the `/in-store/key={storeKey}/customers` endpoint.

## Merchant Center Teams Permissions

The Merchant Center uses Stores for [conditional Team permissions](/merchant-center/administrators-team.md#assign-conditional-permissions-to-a-team). You can define granular permissions for Teams based on their assigned Stores. For example, you can restrict customer service representatives from accessing Customer data for Stores they are not affiliated with, providing greater overall security.

In the Merchant Center, Store-based Team permissions are supported for the following entities:

- Customers
- Orders
- Quotes
- Business Units 
- Cart Discounts
- Product Selections
- Shopping Lists

For a practical step-by-step guide on configuring Merchant Center team permissions with Stores, see [Merchant Center access](/learning-model-your-business-structure/stores-and-channels/apply-stores-and-channels.md#merchant-center-access).

## Data Fencing: Ensuring Data Integrity and Security

Data fencing restricts data access based on Store affiliation. Benefits include:

- **Customer data isolation:** Store-specific Customers only access their Order data within their assigned Store. Global customers have broader access and may be able to see Orders belonging to different Store, but their actions are tracked within the interacting Store's context.
- **Product visibility control:** Product Selections ensure Customers only see relevant Products.
- **Price integrity:** Distribution Channels guarantee Customers see correct Prices.
- **Inventory accuracy:** Supply Channels ensure displayed inventory levels reflect actual stock.

## Product Selections

[Product Selections](/api/projects/product-selections.md) manage the availability of Product Variants for a given Store, allowing merchants to curate specific catalogs for different regions, brands, or customer segments. This is useful for businesses operating multiple Stores within a single commercetools Project. Instead of having all Products available everywhere, Product Selections enable targeted merchandising strategies. This ensures Customers only see relevant Products, contributing to a better shopping experience.

```mermaid
graph RL
 subgraph "commercetools Project"
  Project["Products Data<br/>(Global product catalog)"]
  subgraph Stores
	 StoreA["Zenith Living"]
	 StoreB["Electronics & Tech"]
  end
  ProductSelectionA["Product Selection A<br/>(Subset of products - Inclusion)"]
  ProductSelectionB["Product Selection B<br/>(Subset of products - Inclusion)"]
  ProductSelectionC["Product Selection C<br/>(Subset of products - Inclusion)"]
  subgraph "Product Search"
	 ProductSearch["Product Search Service"]
  end
 end
 CustomerA["API Consumer: Zenith Store filter"]
 CustomerB["API Consumer: Electronics & Tech Store filter"]


 StoreA --> ProductSelectionA
 StoreA --> ProductSelectionC
 StoreB --> ProductSelectionB
 StoreB --> ProductSelectionC
 ProductSearch --> StoreA
 ProductSearch --> StoreB
 ProductSelectionA --> Project
 ProductSelectionB --> Project
 ProductSelectionC --> Project
 CustomerA --> ProductSearch
 CustomerB --> ProductSearch

 click ProductSearch "/../api/projects/product-search" _blank

```

This diagram illustrates how Product Selections work within a commercetools project and how they interact with API consumers. Here's a description of the diagram, from left to right:

- [**Products**](/api/projects/products.md) **Data (Global product catalog):** this is the central repository for all product information within the commercetools Project. It acts as the single source of truth for Product data.
- [**Product Selections**](/merchant-center/product-selections.md)**:** These represent curated subsets of Products from the global catalog. Each Selection list can be created using inclusion or exclusion criteria.
  - Inclusion: allows all or selected Variants of Products to be available on a Store.
  - Exclusion: disallows all or selected Variants of Products from being available on a Store.
  - **Product Selection A:** A selection of products specifically associated with Zenith Living.
  - **Product Selection B:** A selection of products associated with Electronics & Tech.
  - **Product Selection C:** A selection of products that might be shared between both stores or used for a specific campaign.
- [**Stores**](/api/projects/stores.md)**:** this section represents individual Stores within the Project, each having its own specific configuration and potentially a subset of Products from the global catalog, which is achieved by assigning one or more Product Selections to the Store. If a Store has no Product Selections, then it will inherit all Products.
  - **Zenith Living:** a brand specializing in lifestyle products
  - **Electronics & Tech:** a brand focused on electronics and technology products
- [**Product Search**](/api/projects/product-search.md): commercetools’ dedicated Product Search service empowers efficient product discovery. It enables API consumers to search and filter products based on a wide range of criteria. In this particular context, we're focusing on filtering by [Stores](/api/projects/product-search.md#keyword-fields) or [Product Selections](/api/projects/product-search.md#keyword-fields). This capability allows us to leverage the power of Product Selections to curate and deliver tailored product experiences for each storefront or specific customer segment, ensuring relevant and engaging search results.
- **API Consumers:** These represent external systems consuming the Composable APIs.
  - **API Consumer: Zenith Store filter:** this consumer retrieves product information from the Product Search API and filters on the Store Zenith Living which ensures that Products returned belong to the Product Selection for that Store.
  - **API Consumer: Electronics & Tech Store filter:** this consumer retrieves product information from the Product Search API and filters on the Store Electronics & Tech which ensures that Products returned belong to the Product Selection for that Store.

## Related pages

- [Area overview page with navigation](/learning-model-your-business-structure.md)
- [Previous page: Manage multiple experiences from one Project](/learning-model-your-business-structure/stores-and-channels/manage-multiple-experiences-from-one-project.md)
- [Next page: Apply Stores and Channels](/learning-model-your-business-structure/stores-and-channels/apply-stores-and-channels.md)
- [Search documentation and API specs](/search.md)