Documentation
BETA

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 country-specific stores. Currently, a store can hold carts, orders, and customers. Additional settings like languages or channels can be defined in the store and used to query product projections that only contain localized values and prices that are suitable for the store.

During the Beta phase, we plan to let the store define what subset of resources within a project is available in the context of the store, for example which products are sold at what price and which currency or shipping methods can be used.

A store can also be used for permissions. With an OAuth scope like manage_orders:acme-inc:luxury-brand, an API client can only work with carts and orders inside the luxury-brand store, but not within the budget-brand store. See the GraphQL section for more details.

Representations

Store

StoreDraft

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

Set Custom Type

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

  • action - String - "setCustomType"
  • type - ResourceIdentifier to 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).

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}

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