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
id
- Stringversion
- Numberkey
- String
User-specific unique identifier for the store. Thekey
is mandatory and immutable. It is used to reference the store.name
- LocalizedString - Optional
The name of the storelanguages
- Array of Strings - Optional
IETF language tag.distributionChannels
- Set of Reference to a Channel withProductDistribution
ChannelRolesupplyChannels
- Set of Reference to a Channel withInventorySupply
ChannelRolecustom
- CustomFields - OptionalcreatedAt
- DateTimelastModifiedAt
- DateTime
StoreDraft
key
- String
User-specific unique identifier for the store. Thekey
is mandatory and immutable. It is used to reference the store.name
- LocalizedString - Optional
The name of the storelanguages
- Array of Strings - Optional
IETF language tag. Only languages defined in the project can be used.distributionChannels
- Set of ResourceIdentifier to a Channel withProductDistribution
ChannelRole - Optionalcustom
- CustomFieldsDraft - OptionalsupplyChannels
- Set of ResourceIdentifier of Channels withInventorySupply
ChannelRole - Optional
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 the results
array of Store
Query Parameters:
where
- Query Predicate - Optionalsort
- Sort - Optionalexpand
- Expansion - Optionallimit
- Number - Optionaloffset
- Number - Optional
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
action
- String -"setLanguages"
languages
- Array of Strings - Optional
IETF language tag. Only languages defined in the project can be used. An attempt to use other languages will fail with a ProjectNotConfiguredForLanguages error.
Set Distribution Channels
action
- String -"setDistributionChannels"
distributionChannels
- Set of ResourceIdentifier to a Channel withProductDistribution
ChannelRole - Optional
If not defined, the store'sdistributionChannels
are unset. An attempt to use Channel without theProductDistribution
ChannelRole will fail with a MissingRoleOnChannel error.
Add Distribution Channel
action
- String -"addDistributionChannel"
distributionChannel
- ResourceIdentifier to a Channel withProductDistribution
ChannelRole
This action has no effect if given distribution channel is already present in a Store. An attempt to use Channel without theProductDistribution
ChannelRole will fail with a MissingRoleOnChannel error.
Remove Distribution Channel
action
- String -"removeDistributionChannel"
distributionChannel
- ResourceIdentifier to a Channel withProductDistribution
ChannelRole
Set Supply Channels
action
- String -"setSupplyChannels"
supplyChannels
- Set of ResourceIdentifier to a Channel withInventorySupply
ChannelRole - Optional
If not defined, the store'ssupplyChannels
are unset. An attempt to use Channel without theInventorySupply
ChannelRole will fail with a MissingRoleOnChannel error.
Add Supply Channel
action
- String -"addSupplyChannel"
supplyChannel
- ResourceIdentifier to a Channel withInventorySupply
ChannelRole
This action has no effect if given supply channel is already present in a Store. An attempt to use Channel without theInventorySupply
ChannelRole will fail with a MissingRoleOnChannel error.
Remove Supply Channel
action
- String -"removeSupplyChannel"
supplyChannel
- ResourceIdentifier to a Channel withInventorySupply
ChannelRole
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 - Requiredvalue
- Value - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. Ifvalue
is provided, set thevalue
of the field defined by thename
.
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: 1actions: [{ 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
).