Stores

Stores let you model the context your customers shop in

Stores can be used to model e.g. physical retail locations, brand stores, or country-specific stores. Currently, a store holds carts and orders. 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, e.g. which products are sold at what price, and which currency or shipping methods can be used.

Additionally, a store can 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

  • 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
  • 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

Get a Store

Get a Store by ID

Retrieves the representation of a store by its id.

Endpoint: /{projectKey}/stores/{id}
Method: GET
OAuth2 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
OAuth2 Scopes: view_stores:{projectKey}
Response Representation: Store

Query Stores

Endpoint: /{projectKey}/stores
Method: GET
OAuth2 Scopes: view_stores:{projectKey}
Response Representation: PagedQueryResult with the results array of Store
Query Parameters:

Create a Store

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

Update Store

Update Store by ID

Endpoint: /{projectKey}/stores/{id}
Method: POST
OAuth2 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
OAuth2 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

Delete Store

Delete Store by ID

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

  • version - Number - Required

Delete Store by Key

Endpoint: /{projectKey}/stores/key={key}
Method: DELETE
OAuth2 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 (e.g. 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 (e.g. manage_orders:project-key) or with the store-based OAuth permissions (e.g. 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 store(s). 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 (e.g. manage_orders:project-key) or with the store-based OAuth permissions (e.g. 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 (e.g. manage_orders:project-key) or with the store-based OAuth permissions (e.g. manage_orders:project-key:store-key).