Documentation

Store-scoped resources and data fencing

Learn how Store scopes enhance data security and manage data access.

  • After completing this page, you should be able to:

    • Identify the purpose of data fencing in Stores and Channels.
    • Identify Store-scoped API endpoints.
    • Describe how OAuth scopes control data access.

    • Specific resources in Composable Commerce have Store-scoped API versions, providing dedicated endpoints for managing data within a specific Store's context. These include:

    • Carts
    • Cart discounts
    • Orders
    • Quotes
    • Quote Requests
    • Staged Quotes
    • Customers
    • Shopping Lists
    • Product Tailoring

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

    Data fencing with Stores across Composable Commerce resources

    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.

    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.

    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.

    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 permission scoping. Granular permissions can be defined for different Teams or Users based on their assigned Stores. For example, you could restrict customer service representatives from accessing Customer data of Stores they are not affiliated with, providing greater overall security.

    Supported resources for Store permissions include Customers, Orders, Quotes, and Cart Discounts.

    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 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 Composable Commerce 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.

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

    • Products Data (Global product catalog): this is the central repository for all product information within the Composable Commerce Project. It acts as the single source of truth for Product data.
    • Product Selections: 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: 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: Composable Commerce’s 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 or Product Selections. 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.

    Test your knowledge