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. 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. For more information, see the Helpers section.
Representations
Store
id String | Unique ID of the Store. |
version Int | Current version of the Store. |
key String | User-defined unique and immutable identifier for the Store. MinLength:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
name | Name of the Store. |
languages Array of Locale | Languages configured for the Store. |
countries Array of StoreCountry | Countries defined for the Store. |
distributionChannels Array of ChannelReference | Product Distribution Channels allowed for the Store. MaxItems:100 |
supplyChannels Array of ChannelReference | Inventory Supply Channels allowed for the Store. MaxItems:100 |
productSelections Array of ProductSelectionSetting | Controls availability of Products for this Store via Product Selections:
100 |
custom | Custom fields for the Store. |
createdAt | Date and time (UTC) the Store was initially created. |
createdBy BETA | IDs and references that created the Store. |
lastModifiedAt | Date and time (UTC) the Store was last updated. |
lastModifiedBy BETA | IDs and references that last modified the Store. |
StoreCountry
code | Two-digit country code as per ISO 3166-1 alpha-2. |
StoreDraft
key String | User-defined unique and immutable identifier for the Store. Keys can only contain alphanumeric characters, underscores, and hyphens. MinLength:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
name | Name of the Store. |
languages Array of Locale | Languages defined in Project. Only languages defined in the Project can be used. |
countries Array of StoreCountry | Countries defined for the Store. |
distributionChannels Array of ChannelResourceIdentifier | ResourceIdentifier of a Channel with 100 |
supplyChannels Array of ChannelResourceIdentifier | ResourceIdentifier of a Channel with 100 |
productSelections Array of ProductSelectionSettingDraft | Controls availability of Products for this Store via active/inactive Product Selections:
100 |
custom | Custom fields for the Store. |
StorePagedQueryResponse
PagedQueryResult with results containing an array of Store.
limit Int | Number of results requested. |
offset Int | Number of elements skipped. |
count Int | Actual number of results returned. |
total Int | Total number of results matching the query.
This number is an estimation that is not strongly consistent.
This field is returned by default.
For improved performance, calculating this field can be deactivated by using the query parameter |
results Array of Store | Stores matching the query. |
StoreReference
id String | Unique ID of the referenced Store. |
typeId | "store" References a Store. |
obj | Contains the representation of the expanded Store. Only present in responses to requests with Reference Expansion for Stores. |
StoreResourceIdentifier
ResourceIdentifier to a Store. Either id
or key
is required. If both are set, an InvalidJsonInput error is returned.
StoreKeyReference
KeyReference to a Store.
ProductSelectionSetting
productSelection | Reference to a ProductSelection. |
active Boolean | If |
ProductSelectionSettingDraft
productSelection | Resource Identifier of a ProductSelection. |
active Boolean | Set to false |
Get Store
Get Store by ID
view_stores:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/stores/{id} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"id": "c2f93299-c967-44af-8c2a-d2220bf39eb2","version": 1,"key": "random-key-12314","name": {"en": "big store"},"languages": [],"countries": [],"distributionChannels": [],"supplyChannels": [],"productSelections": [],"createdAt": "1971-01-01T00:00:00.001Z","lastModifiedAt": "1972-01-01T00:00:00.001Z"}
Get Store by Key
view_stores:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/stores/key={key} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"id": "c2f93299-c967-44af-8c2a-d2220bf39eb2","version": 1,"key": "random-key-12314","name": {"en": "big store"},"languages": [],"countries": [],"distributionChannels": [],"supplyChannels": [],"productSelections": [],"createdAt": "1971-01-01T00:00:00.001Z","lastModifiedAt": "1972-01-01T00:00:00.001Z"}
Query Stores
view_stores:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
where | The parameter can be passed multiple times. |
/^var[.][a-zA-Z0-9]+$/ Any string parameter matching this regular expression | Predicate parameter values. The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limit Int | Number of results requested. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to Default: true |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/stores -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"limit": 20,"offset": 0,"count": 2,"total": 2,"results": [{"id": "c2f93299-c967-44af-8c2a-d2220bf39eb2","version": 1,"key": "random-key-12314","name": {"en": "big store"},"languages": [],"countries": [],"distributionChannels": [],"supplyChannels": [],"productSelections": [],"createdAt": "1971-01-01T00:00:00.001Z","lastModifiedAt": "1972-01-01T00:00:00.001Z"},{"id": "c2f93209-c967-44af-8c2a-d2220bf39eb2","version": 1,"key": "random-key-1234314","name": {"en": "second store"},"languages": [],"countries": [],"distributionChannels": [],"supplyChannels": [],"productSelections": [],"createdAt": "1973-01-01T00:00:00.001Z","lastModifiedAt": "1973-01-01T00:00:00.001Z"}]}
Check if Store exists
Check if Store exists by ID
Checks if a Store exists for a given id
. Returns a 200 OK
status if the Store exists or a 404 Not Found
otherwise.
view_states:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/stores/{id} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Store exists by Key
Checks if a Store exists for a given key
. Returns a 200 OK
status if the Store exists or a 404 Not Found
otherwise.
view_stores:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/stores/key={key} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Store exists by Query Predicate
Checks if a Store exists for a given Query Predicate. Returns a 200 OK
status if any Stores match the Query Predicate or a 404 Not Found
otherwise.
view_stores:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
where |
curl --head https://api.{region}.commercetools.com/{projectKey}/stores -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
Create Store
manage_stores:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/stores -i \--header "Authorization: Bearer ${BEARER_TOKEN}" \--header 'Content-Type: application/json' \--data-binary @- << DATA{"key" : "random-key-123","name" : {"en" : "main store"}}DATA
{"id": "c2f93299-c967-44af-8c2a-d2220bf39eb2","version": 1,"key": "random-key-12314","name": {"en": "big store"},"languages": [],"countries": [],"distributionChannels": [],"supplyChannels": [],"productSelections": [],"createdAt": "1971-01-01T00:00:00.001Z","lastModifiedAt": "1972-01-01T00:00:00.001Z"}
Specific error codes:
Update Store
Update Store by ID
manage_stores:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
application/json
version Int | Expected version of the Store on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions Array of StoreUpdateAction | Update actions to be performed on the Store. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/stores/{id} -i \--header "Authorization: Bearer ${BEARER_TOKEN}" \--header 'Content-Type: application/json' \--data-binary @- << DATA{"version" : 1,"actions" : [ {"action" : "setName","name" : {"en" : "New Name"}} ]}DATA
{"id": "c2f93299-c967-44af-8c2a-d2220bf39eb2","version": 1,"key": "random-key-12314","name": {"en": "big store"},"languages": [],"countries": [],"distributionChannels": [],"supplyChannels": [],"productSelections": [],"createdAt": "1971-01-01T00:00:00.001Z","lastModifiedAt": "1972-01-01T00:00:00.001Z"}
Update Store by Key
manage_stores:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
application/json
version Int | Expected version of the Store on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions Array of StoreUpdateAction | Update actions to be performed on the Store. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/stores/key={key} -i \--header "Authorization: Bearer ${BEARER_TOKEN}" \--header 'Content-Type: application/json' \--data-binary @- << DATA{"version" : 1,"actions" : [ {"action" : "setName","name" : {"en" : "New Name"}} ]}DATA
{"id": "c2f93299-c967-44af-8c2a-d2220bf39eb2","version": 1,"key": "random-key-12314","name": {"en": "big store"},"languages": [],"countries": [],"distributionChannels": [],"supplyChannels": [],"productSelections": [],"createdAt": "1971-01-01T00:00:00.001Z","lastModifiedAt": "1972-01-01T00:00:00.001Z"}
Update actions
Set Name
This update action produces the StoreNameSet Message.
action String | "setName" |
name | Value to set. |
{"action": "setName","name": {"en": "New Name"}}
Set Languages
This update action produces the StoreLanguagesChanged Message. Adding a language other than the ones defined in the Project returns a ProjectNotConfiguredForLanguages error.
action String | "setLanguages" |
languages Array of Locale | Value to set. |
{"action": "setLanguages","languages": ["en"]}
Set Countries
This update action produces the StoreCountriesChanged Message.
action String | "setCountries" |
countries Array of StoreCountry | New value to set. |
{"action": "setCountries","countries": [{"code": "DE"},{"code": "IT"}]}
Add Country
This update action produces the StoreCountriesChanged Message. It has no effect if the given country is already present in a Store.
action String | "addCountry" |
country | Value to append to |
{"action": "addCountry","country": {"code": "DE"}}
Remove Country
This update action produces the StoreCountriesChanged Message. It has no effect if a given country is not present in a Store.
action String | "removeCountry" |
country | Value to remove from |
{"action": "removeCountry","country": {"code": "DE"}}
Set Distribution Channels
This update action produces the StoreDistributionChannelsChanged Message.
Setting a Channel without the ProductDistribution
ChannelRoleEnum returns a MissingRoleOnChannel error.
action String | "setDistributionChannels" |
distributionChannels Array of ChannelResourceIdentifier | Value to set.
If not defined, the Store's 100 |
{"action": "setDistributionChannels","distributionChannels": [{"typeId": "channel","id": "12345"}]}
Add Distribution Channel
This update action produces the StoreDistributionChannelsChanged Message. It has no effect if a given distribution channel is already present in a Store.
Adding a Channel without the ProductDistribution
ChannelRoleEnum returns a MissingRoleOnChannel error.
action String | "addDistributionChannel" |
distributionChannel | Value to append. |
{"action": "addDistributionChannel","distributionChannel": {"typeId": "channel","id": "12345"}}
Remove Distribution Channel
This update action produces the StoreDistributionChannelsChanged Message.
action String | "removeDistributionChannel" |
distributionChannel | Value to remove. ResourceIdentifier of a Channel with the |
{"action": "removeDistributionChannel","distributionChannel": {"typeId": "channel","id": "12345"}}
Set Supply Channels
Setting a supply channel produces the StoreSupplyChannelsChanged Message.
Setting a Channel without the InventorySupply
ChannelRoleEnum returns a MissingRoleOnChannel error.
action String | "setSupplyChannels" |
supplyChannels Array of ChannelResourceIdentifier | Value to set.
If not defined, the Store's 100 |
{"action": "setSupplyChannels","supplyChannels": [{"typeId": "channel","id": "12345"}]}
Add Supply Channel
This action has no effect if a given supply channel is already present in a Store.
Adding a supply channel produces the StoreSupplyChannelsChanged Message.
Adding a Channel without the InventorySupply
ChannelRoleEnum returns a MissingRoleOnChannel error.
action String | "addSupplyChannel" |
supplyChannel | Value to append. |
{"action": "addSupplyChannel","supplyChannel": {"typeId": "channel","id": "12345"}}
Remove Supply Channel
This update action produces the StoreSupplyChannelsChanged Message.
action String | "removeSupplyChannel" |
supplyChannel | Value to remove. ResourceIdentifier of a Channel with the |
{"action": "removeSupplyChannel","supplyChannel": {"typeId": "channel","id": "12345"}}
Add Product Selection
To make all included Products available to your customers of a given Store, add the Product Selections to the respective Store. This action has no effect if the given Product Selection is already present in the Store and has the same active
flag.
action String | "addProductSelection" |
productSelection | Product Selection to add to the Store either activated or deactivated. |
active Boolean | Set to false |
{"action": "addProductSelection","productSelection": {"typeId": "product-selection","id": "e7ba4555-b1bb-483d-92d8-2c4a10778427"},"active": false}
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.
A Store without any Product Selection includes all Products of a Project.
The number of Product Selections configured for a Store is limited to 100
.
Remove Product Selection
This action has no effect if the given Product Selection is not in the Store.
action String | "removeProductSelection" |
productSelection | Value to remove. The removed Product Selection is made offline. |
{"action": "removeProductSelection","productSelection": {"typeId": "product-selection","id": "e7ba4555-b1bb-483d-92d8-2c4a10778427"}}
Set Product Selections
Instead of adding or removing Product Selections individually, you can also change all the Store's Product Selections in one go using this update action. The Store will only contain the Product Selections specified in the request.
action String | "setProductSelections" |
productSelections Array of ProductSelectionSettingDraft | Value to set.
100 |
{"action": "setProductSelections","productSelections": [{"productSelection": {"typeId": "product-selection","id": "e7ba4555-b1bb-483d-92d8-2c4a10778427"},"active": false},{"productSelection": {"typeId": "product-selection","id": "a7ba45e5-b1c2-482d-94d5-2c1a10118426"},"active": true}]}
The number of Product Selections configured for a Store is limited to 100
.
Change Product Selection Active
ProductSelection in a Store can be activated or deactivated using this update action.
action String | "changeProductSelectionActive" |
productSelection | Current Product Selection of the Store to be activated or deactivated. |
active Boolean | Set to false |
{"action": "changeProductSelectionActive","productSelection": {"typeId": "product-selection","id": "e7ba4555-b1bb-483d-92d8-2c4a10778427"},"active": true}
Set Custom Type
action String | "setCustomType" |
type | Defines the Type that extends the Store with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Store. |
fields | Sets the Custom Fields fields for the Store. |
{"action": "setCustomType","type": {"id": "{{type-id}}","typeId": "type"},"fields": {"exampleStringField": "TextString"}}
Set CustomField
action String | "setCustomField" |
name String | Name of the Custom Field. |
value | If |
{"action": "setCustomField","name": "exampleStringField","value": "TextString"}
Delete Store
Delete Store by ID
manage_stores:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
version Int | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/stores/{id}?version={version} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"id": "c2f93299-c967-44af-8c2a-d2220bf39eb2","version": 1,"key": "random-key-12314","name": {"en": "big store"},"languages": [],"countries": [],"distributionChannels": [],"supplyChannels": [],"productSelections": [],"createdAt": "1971-01-01T00:00:00.001Z","lastModifiedAt": "1972-01-01T00:00:00.001Z"}
Delete Store by Key
manage_stores:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
version Int | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/stores/key={key}?version={version} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"id": "c2f93299-c967-44af-8c2a-d2220bf39eb2","version": 1,"key": "random-key-12314","name": {"en": "big store"},"languages": [],"countries": [],"distributionChannels": [],"supplyChannels": [],"productSelections": [],"createdAt": "1971-01-01T00:00:00.001Z","lastModifiedAt": "1972-01-01T00:00:00.001Z"}
Helpers in the HTTP and GraphQL APIs
commercetools Composable Commerce provides some helper methods for accessing resources within a specified Store.
In-Store representations
The In Store methods provide access to resources projected to the specified Store. Store-projected representations are supported for the following resources:
To access these endpoints your API Client requires store-related scopes, such as manage_orders:{projectKey}:{storeKey}
.
Products available in Store
Store's active Product Selection(s) form its assortment. Or, in other words, a Product is considered available in a Store if it is:
- not excluded by any of that Store's active Product Selection with
IndividualExclusion
ProductSelectionMode. - included in at least one of that Store's active Product Selections with
Individual
ProductSelectionMode.
When a Product is part of a Store's active Product Selection and has associated Variant Selection, its In-Store representation is projected such that only selected Product Variants are present.
When a Store has two, or more, active Product Selection(s) that contain the same Product but have different Variant Selections, Product's In-Store representation is resolved in following manner:
- All Product Variants that are part of a Variant Exclusion across Product Selections are discarded.
- All Product Variants that are part of a Variant Selection of type IncludeOnly across Product Selections are kept, with the exception of ones that are part of a Variant Selection of type IncludeAllExcept.
If Product's Variant Selection excludes all of the Product's Variants or if the Product is assigned to a Product Selection with mode IndividualExclusion
without specifying any Variant Exclusion, the Product is considered as absent in the Store.
The Store configuration is cached up to one minute as it is not expected to change frequently. Take that delay into account when fetching any projected Product in the Store.
GraphQL query fields
The top-level fields inStore
and inStores
are available to only query resources belonging to specified Stores. For example, the following query only returns IDs of Carts created in the luxury-brand
Store, 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"])
performs 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
or manage_orders:project-key:budget-brand
, else 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
).