Documentation

Stores

Stores let you model the context your customers shop in

Stores can be used to model, for example, physical retail locations, brand stores, or regions. They allow to define what subset of resources within a project is available in the context of a store.

Currently, a Store can hold Carts, Orders, Shopping Lists, Customers, and Products BETA. For managing the availability of product assortments for your store, use Product Selections. Additional settings like languages or channels for inventory and pricing can be defined in the Store and used to query Product Projections that only contain localized values, inventory data and Prices that are suitable for the Store.

Permissions can be granted for particular Stores only. For example, with an OAuth Scope like manage_orders:acme-inc:luxury-brand, an API Client can only access Carts and Orders inside the luxury-brand Store, but not within the budget-brand Store. See the Helpers section below for more details.

Representations

Store

  • id - String
  • version - Number
  • key - String
    User-specific unique identifier for the store. The key is mandatory and immutable. It is used to reference the store.
  • name - LocalizedString - Optional
    The name of the store
  • languages - Array of Strings - Optional
    IETF language tag.
  • distributionChannels - Set of Reference to a Channel with ProductDistribution ChannelRole
  • supplyChannels - Set of Reference to a Channel with InventorySupply ChannelRole
  • productSelections - Array of ProductSelectionSetting BETA
    If empty, all Products in the Project are available in this Store. If not empty, those Product Selections are available in the Store for which the active setting is true.
  • custom - CustomFields - Optional
  • createdAt - DateTime
  • lastModifiedAt - DateTime

StoreDraft

  • key - String
    User-specific unique identifier for the store. The key is mandatory and immutable. It is used to reference the store.
  • name - LocalizedString - Optional
    The name of the store
  • languages - Array of Strings - Optional
    IETF language tag. Only languages defined in the project can be used.
  • distributionChannels - Set of ResourceIdentifier of a Channel with ProductDistribution ChannelRole - Optional
  • custom - CustomFieldsDraft - Optional
  • supplyChannels - Set of ResourceIdentifier of Channels with InventorySupply ChannelRole - Optional
  • productSelections - Array of ProductSelectionSettingDraft BETA - Optional
    If not provided or empty, all Products in the Project are available in this Store. If provided, those Product Selections are available in the Store for which the active setting is true.

ProductSelectionSetting BETA

This setting specifies whether the referenced Product Selection is available in the Store.

  • productSelection - Reference to a ProductSelection
  • active - Boolean
    If true the Products assigned to this Product Selection are part of the Store's assortment.

ProductSelectionSettingDraft BETA

This setting specifies whether the referenced Product Selection is available in the Store.

  • productSelection - ResourceIdentifier to a ProductSelection
  • active - Boolean - Optional, defaults to false.
    If true the Products assigned to this Product Selection are part of the Store's assortment.

Get a Store

Get a Store by ID

Retrieves the representation of a store by its id.

Endpoint: /{projectKey}/stores/{id}
Method: GET
OAuth 2.0 Scopes: view_stores:{projectKey}
Response Representation: Store

Get a Store by Key

Retrieves the representation of a store by its key.

Endpoint: /{projectKey}/stores/key={key}
Method: GET
OAuth 2.0 Scopes: view_stores:{projectKey}
Response Representation: Store

Query Stores

Endpoint: /{projectKey}/stores
Method: GET
OAuth 2.0 Scopes: view_stores:{projectKey}
Response Representation: PagedQueryResult with results containing an array of Store
Query Parameters:

Create a Store

Endpoint: /{projectKey}/stores
Method: POST
OAuth 2.0 Scopes: manage_stores:{projectKey}
Request Representation: StoreDraft
Response Representation: Store

Update Store

Update Store by ID

Endpoint: /{projectKey}/stores/{id}
Method: POST
OAuth 2.0 Scopes: manage_stores:{projectKey}
Response Representation: Store
Fields:

  • version - Number - Required
    The expected version of the store on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the store.

Update Store by Key

Endpoint: /{projectKey}/stores/key={key}
Method: POST
OAuth 2.0 Scopes: manage_stores:{projectKey}
Response Representation: Store
Fields:

  • version - Number - Required
    The expected version of the store on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the store.

Update actions

Set Name

  • action - String - "setName"
  • name - LocalizedString - Optional
    The updated name of the store

Set Languages

Set Distribution Channels

Add Distribution Channel

Remove Distribution Channel

Set Supply Channels

Add Supply Channel

Remove Supply Channel

Add Product Selection BETA

To make all included Products available to your customers of a given Store, add the Product Selection to the respective Store.

  • action - String - "addProductSelection"
  • productSelection - ProductSelectionSettingDraft
    This action has no effect if the given Product Selection is already present in the Store and has the same active flag.

A Store can incorporate multiple Product Selections, which is useful if a Product Selection is shared between Stores. For example, you may want to create a shared Product Selection as your base catalog which is supplemented by individual Product Selections for each Store.

Note: A Store without any Product Selection includes all Products of a Project.

During the public beta period the number of Product Selections configured for a Store is limited to 100.

Remove Product Selection BETA

To take a Product Selection offline, just remove it from the respective Store.

  • action - String - "removeProductSelection"
  • productSelection - ResourceIdentifier to a ProductSelection
    This action has no effect if the given Product Selection is not in the Store.

Set Product Selections BETA

Instead of adding or removing Product Selections individually, you can also change all the Store’s Product Selections in one go using the following update action. The Store will then only contain the Product Selections specified in the request.

  • action - String - "setProductSelections"
  • productSelections - Array of ProductSelectionSettingDraft BETA - Optional
    If not provided or empty, all Products in the Project are available in this Store. If provided, those Product Selections are available in the Store for which the active setting is true.

During the public beta period the number of Product Selections configured for a Store is limited to 100.

Change Product Selection Active BETA

This update action allows activation or deactivation of a ProductSelection in a Store.

  • action - String - "changeProductSelectionActive"
  • productSelection - ResourceIdentifier to a ProductSelection
  • active - Boolean - Optional, defaults to false.
    To make Products of the given selection available in the Store you have to activate the collection in the Store.

Set Custom Type

This action sets, overwrites, or removes any existing custom type and fields for an existing store.

  • action - String - "setCustomType"
  • type - ResourceIdentifier of a Type - Optional
    If set, the custom type is reset to this value.
    If absent, the custom type and any existing custom fields are removed.
  • fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
    Sets the custom field to this value.

Set CustomField

This action sets, overwrites, or removes any existing custom field for an existing store.

  • action - String - "setCustomField"
  • name - String - Required
  • value - Value - Optional
    If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

Delete Store

Delete Store by ID

Endpoint: /{projectKey}/stores/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_stores:{projectKey}
Query Parameters:

  • version - Number - Required

Delete Store by Key

Endpoint: /{projectKey}/stores/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_stores:{projectKey}
Query Parameters:

  • version - Number - Required

Helpers in the HTTP API and the GraphQL API

To access or modify carts, orders, and customers belonging to a store, some helpers are available both in the HTTP API and the GraphQL API. These can optionally also be used with the store-based OAuth permissions (for example manage_orders:project-key:store-key).

Since the Store configuration is not expected to change frequently it is cached up to one minute. Take that delay into account when fetching any projected Product in the Store.

HTTP API endpoints

To access or modify resources belonging to a specific store, a different URL can be used. As an example, the following query will only return ids of carts that have been created in the store luxury-brand, and the total field counts only carts within that store:

GET /project/in-store/key=luxury-brand/carts

To create a cart in this store, you can use:

POST /project/in-store/key=luxury-brand/carts

The following example will only update the cart if it is in the luxury-brand store. Otherwise, a 404 error will be returned.

POST /project/in-store/key=luxury-brand/carts/{cart-id}

The following endpoints can be used to retrieve product details about a particular Product in a specific Store. BETA

GET /project/in-store/key={store-key}/product-projections/{product-id}

GET /project/in-store/key={store-key}/product-projections/key={product-key}

The following endpoint can be used to retrieve Products assigned to a Store via active Product Selections. BETA

GET /project/in-store/key={storeKey}/product-selection-assignments

These can either be used with regular OAuth permissions (for example manage_orders:project-key) or with the store-based OAuth permissions (for example manage_orders:project-key:store-key). For these examples, the OAuth scope must contain either manage_orders:project-key or manage_orders:project-key:luxury-brand, otherwise an insufficient_scope error is returned.

For more information, see:

GraphQL query fields

The top-level fields inStore and inStores are available to only query resources belonging to the specified stores. As an example, the following query will only return ids of carts that have been created in the store luxury-brand, and the total field counts only carts within that store:

query {
  inStore(key: "luxury-brand") {
    carts {
      results {
        id
      }
      total
    }
  }
}

Similarly, inStores(keys: ["luxury-brand", "budget-brand"]) will perform the queries only within these two stores.

Both can either be used with regular OAuth permissions (for example manage_orders:project-key) or with the store-based OAuth permissions (for example manage_orders:project-key:store-key). For the inStores example, the OAuth scope must contain manage_orders:project-key:luxury-brand manage_orders:project-key:budget-brand, otherwise an insufficient_scope error is returned.

GraphQL mutations

Mutations on carts, orders, and customers have an optional argument called storeKey. In the following example, the cart is created in the store luxury-brand:

mutation {
  createCart(
    draft: {
      currency: "USD"
    }
    storeKey: "luxury-brand"
  )
  {
    id
  }
}

The following update to the cart is only performed if the cart is in the store luxury-brand:

mutation {
  updateCart(
    id: "123e4567-e89b-12d3-a456-426655440000"
    version: 1
    actions: [{ addLineItem: { sku: "..." }}]
    storeKey: "luxury-brand"
  )
  {
    id
  }
}

This can either be used with regular OAuth permissions (for example manage_orders:project-key) or with the store-based OAuth permissions (for example manage_orders:project-key:store-key).