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. For more information, see the Helpers section.

Representations

Store

StoreDraft

StorePagedQueryResponse

StoreReference

StoreResourceIdentifier

StoreKeyReference

ProductSelectionSetting

ProductSelectionSettingDraft

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_-]+$`
`createdAt` DateTime	Date and time (UTC) the Store was initially created.
`createdBy`BETA CreatedBy	Present on resources created after 1 February 2019 except for events not tracked.
`lastModifiedAt` DateTime	Date and time (UTC) the Store was last updated.
`lastModifiedBy`BETA LastModifiedBy	Present on resources created after 1 February 2019 except for events not tracked.
`name` LocalizedString	Name of the Store.
`languages` Array of Locale	Languages configured for the Store.
`distributionChannels` Array of ChannelReference	Product Distribution Channels allowed for the Store.
`supplyChannels` Array of ChannelReference	Inventory Supply Channels allowed for the Store.
`productSelections`BETA Array of ProductSelectionSetting	Controls availability of Products for this Store via active Product Selections. If empty all Products in the Project are available in this Store. If provided, Products from `active` Product Selections are available in this Store.
`custom` CustomFields	Custom fields for the Store.

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` LocalizedString	Name of the Store.
`languages` Array of Locale	Languages defined in Project. Only languages defined in the Project can be used.
`distributionChannels` Array of ChannelResourceIdentifier	ResourceIdentifier to a Channel with `ProductDistribution` ChannelRoleEnum.
`supplyChannels` Array of ChannelResourceIdentifier	ResourceIdentifier to a Channel with `InventorySupply` ChannelRoleEnum.
`productSelections`BETA Array of ProductSelectionSettingDraft	Controls availability of Products for this Store via active Product Selections. Leave empty if all Products in the Project should be available in this Store. If provided, Products from `active` Product Selections are available in this Store.
`custom` CustomFieldsDraft	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 `withTotal=false`. When the results are filtered with a Query Predicate, `total` is subject to a limit.
`results` Array of Store	Stores matching the query.

StoreReference

Reference to a Store.

`id` String	Unique ID of the referenced Store.
`typeId` String	`"store"` References a Store.
`obj` Store	Contains the representation of the expanded Store. Only present in responses to requests with Reference Expansion for Stores.

StoreResourceIdentifier

ResourceIdentifier to a Store.

`id` String	Unique ID of the referenced Store. Either `id` or `key` is required.
`key` String	Unique key of the referenced Store. Either `id` or `key` is required.
`typeId` String	`"store"` References a Store.

StoreKeyReference

Reference to a Store by its key.

`key` String	Unique and immutable key of the referenced Store.
`typeId` String	`"store"` References a Store.

ProductSelectionSetting BETA

`productSelection` ProductSelectionReference	Reference to a ProductSelection.
`active` Boolean	If `true`, all Products assigned to this Product Selection are part of the Store's assortment.

ProductSelectionSettingDraft BETA

`productSelection` ProductSelectionResourceIdentifier	Resource Identifier of a ProductSelection.
`active` Boolean	Set to `true` if all Products assigned to the Product Selection should become part of the Store's assortment. Default: `false`

Get Store

Get Store by ID

GET

https://api.{region}.commercetools.com/{projectKey}/stores/{id}

OAuth 2.0 Scopes:

view_stores:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the Store.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200Store

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/stores/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Get Store by Key

GET

https://api.{region}.commercetools.com/{projectKey}/stores/key={key}

OAuth 2.0 Scopes:

view_stores:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the Store.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200Store

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/stores/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Query Stores

GET

https://api.{region}.commercetools.com/{projectKey}/stores

OAuth 2.0 Scopes:

view_stores:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

`where` QueryPredicate	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` Sort	The parameter can be passed multiple times.
`expand` Expansion	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 `false` to improve query performance when the `total` is not needed.

Response:

200StorePagedQueryResponse

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/stores -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create Store

POST

https://api.{region}.commercetools.com/{projectKey}/stores

OAuth 2.0 Scopes:

manage_stores:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:StoreDraft

Response:

201Store

Request Example:cURL

curl -X POST 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

Update Store

Update Store by ID

POST

https://api.{region}.commercetools.com/{projectKey}/stores/{id}

OAuth 2.0 Scopes:

manage_stores:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the Store.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:

`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 409 Conflict will be returned.
`actions` Array of StoreUpdateAction	Update actions to be performed on the Store.

Response:

200Store

Request Example:cURL

curl -X POST 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

Update Store by Key

POST

https://api.{region}.commercetools.com/{projectKey}/stores/key={key}

OAuth 2.0 Scopes:

manage_stores:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the Store.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:

`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 409 Conflict will be returned.
`actions` Array of StoreUpdateAction	Update actions to be performed on the Store.

Response:

200Store

Request Example:cURL

curl -X POST 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

Update actions

Set Name

Set Languages

Set Distribution Channels

Add Distribution Channel

Remove Distribution Channel

Set Supply Channels

Add Supply Channel

Remove Supply Channel

Add Product Selection

Remove Product Selection

Set Product Selections

Change Product Selection Active

Set Custom Type

Set CustomField

Set Name

`action` String	`"setName"`
`name` LocalizedString	Value to set.

Example: json

{
  "action" : "setName",
  "name" : {
    "en" : "New Name"
  }
}

Set Languages

`action` String	`"setLanguages"`
`languages` Array of Locale	Value to set. Any attempt to use languages other than the ones defined in the Project will fail with a ProjectNotConfiguredForLanguages error.

Example: json

{
  "action" : "setLanguages",
  "languages" : [ "en" ]
}

Set Distribution Channels

`action` String	`"setDistributionChannels"`
`distributionChannels` Array of ChannelResourceIdentifier	Value to set. If not defined, the Store's `distributionChannels` are unset. Any attempt to use Channel without the `ProductDistribution` ChannelRoleEnum will fail with a MissingRoleOnChannel error.

Example: json

{
  "action" : "setDistributionChannels",
  "distributionChannels" : [ {
    "typeId" : "channel",
    "id" : "12345"
  } ]
}

Add Distribution Channel

This action has no effect if a given distribution channel is already present in a Store.

`action` String	`"addDistributionChannel"`
`distributionChannel` ChannelResourceIdentifier	Value to append. Any attempt to use Channel without the `ProductDistribution` ChannelRoleEnum will fail with a MissingRoleOnChannelError error.

Example: json

{
  "action" : "addDistributionChannel",
  "distributionChannel" : {
    "typeId" : "channel",
    "id" : "12345"
  }
}

Remove Distribution Channel

`action` String	`"removeDistributionChannel"`
`distributionChannel` ChannelResourceIdentifier	Value to remove. ResourceIdentifier of a Channel with the `ProductDistribution` ChannelRoleEnum.

Example: json

{
  "action" : "removeDistributionChannel",
  "distributionChannel" : {
    "typeId" : "channel",
    "id" : "12345"
  }
}

Set Supply Channels

`action` String	`"setSupplyChannels"`
`supplyChannels` Array of ChannelResourceIdentifier	Value to set. If not defined, the Store's `supplyChannels` are unset. Any attempt to use Channel without the `InventorySupply` ChannelRoleEnum will fail with a MissingRoleOnChannel error.

Example: json

{
  "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.

`action` String	`"addSupplyChannel"`
`supplyChannel` ChannelResourceIdentifier	Any attempt to use Channel without the `InventorySupply` ChannelRoleEnum will fail with a MissingRoleOnChannel error.

Example: json

{
  "action" : "addSupplyChannel",
  "supplyChannel" : {
    "typeId" : "channel",
    "id" : "12345"
  }
}

Remove Supply Channel

`action` String	`"removeSupplyChannel"`
`supplyChannel` ChannelResourceIdentifier	Value to remove. ResourceIdentifier of a Channel with the `InventorySupply` ChannelRoleEnum.

Example: json

{
  "action" : "removeSupplyChannel",
  "supplyChannel" : {
    "typeId" : "channel",
    "id" : "12345"
  }
}

Add Product Selection BETA

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` ProductSelectionResourceIdentifier	Product Selection to add to the Store either activated or deactivated.
`active` Boolean	Set to `true` to make all Products assigned to the referenced Product Selection available in the Store. Default: `false`

Example: json

{
  "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.

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

Remove Product Selection BETA

This action has no effect if the given Product Selection is not in the Store.

`action` String	`"removeProductSelection"`
`productSelection` ProductSelectionResourceIdentifier	Value to remove. The removed Product Selection is made offline.

Example: json

{
  "action" : "removeProductSelection",
  "productSelection" : {
    "typeId" : "product-selection",
    "id" : "e7ba4555-b1bb-483d-92d8-2c4a10778427"
  }
}

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 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. If provided, Product Selections for which `active` is set to `true` are available in the Store. If not provided or provided as empty array, the action removes all Product Selections from this Store, meaning all Products in the Project are available in this Store.

Example: json

{
  "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
  } ]
}

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

Change Product Selection Active BETA

ProductSelection in a Store can be activated or deactivated using this update action.

`action` String	`"changeProductSelectionActive"`
`productSelection` ProductSelectionResourceIdentifier	Current Product Selection of the Store to be activated or deactivated.
`active` Boolean	Set to `true` if all Products assigned to the Product Selection should become part of the Store's assortment. Default: `false`

Example: json

{
  "action" : "changeProductSelectionActive",
  "productSelection" : {
    "typeId" : "product-selection",
    "id" : "e7ba4555-b1bb-483d-92d8-2c4a10778427"
  },
  "active" : true
}

Set Custom Type

`action` String	`"setCustomType"`
`type` TypeResourceIdentifier	Defines the Type that extends the Store with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Store.
`fields` FieldContainer	Sets the Custom Fields fields for the Store.

Example: json

{
  "action" : "setCustomType",
  "type" : {
    "id" : "{{type-id}}",
    "typeId" : "type"
  },
  "fields" : {
    "examplaryStringTypeField" : "TextString"
  }
}

Set CustomField

`action` String	`"setCustomField"`
`name` String	Name of the Custom Field.
`value` CustomFieldValue	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, it is set for the field defined by `name`.

Example: json

{
  "action" : "setCustomField",
  "name" : "ExamplaryStringTypeField",
  "value" : "TextString"
}

Delete Store

Delete Store by ID

DELETE

https://api.{region}.commercetools.com/{projectKey}/stores/{id}

OAuth 2.0 Scopes:

manage_stores:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the Store.

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`version` Int	Last seen version of the resource.

Response:

200Store

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/stores/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Delete Store by Key

DELETE

https://api.{region}.commercetools.com/{projectKey}/stores/key={key}

OAuth 2.0 Scopes:

manage_stores:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the Store.

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`version` Int	Last seen version of the resource.

Response:

200Store

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/stores/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Helpers in the HTTP and GraphQL APIs

To access or modify Carts, My Carts, Orders, My Orders, Customers, and Product Selections belonging to a Store, some helpers are available in the HTTP and GraphQL APIs. The following endpoints contain the in-store/key={storeKey} path segment and they can be used with the store-based OAuth permissions, such as manage_orders:project-key:store-key.

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

Query Carts in Store

GET

https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts

Queries carts in a specific Store.

OAuth 2.0 Scopes:

view_orders:{projectKey}, view_orders:{projectKey}:{storeKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`storeKey` String	`key` of the Store.

Query parameters:

`where` QueryPredicate	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` Sort	The parameter can be passed multiple times.
`expand` Expansion	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 `false` to improve query performance when the `total` is not needed.

Response:

200CartPagedQueryResponse

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create Cart in Store

POST

https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts

Creates a Cart in the Store specified by storeKey. When using this endpoint the Cart's store field is always set to the store specified in the path parameter. Creating a Cart can fail with an InvalidOperationError if the referenced ShippingMethod in the CartDraft has a predicate which does not match the Cart.

OAuth 2.0 Scopes:

manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`storeKey` String	`key` of the Store.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:CartDraft

Response:

201Cart

Request Example:cURL

curl -X POST https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "currency" : "EUR"
}
DATA

Update Cart in Store

POST

https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id}

Updates a Cart in the Store specified by storeKey. If the Cart exists in the Project but does not have the store field, or the store field references a different Store, this method returns a ResourceNotFoundError.

OAuth 2.0 Scopes:

manage_orders:{projectKey}, manage_orders:{projectKey}:{storeKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`storeKey` String	`key` of the Store.
`id` String	`id` of the Cart.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:

`version` Int
`actions` Array of CartUpdateAction

Response:

200Cart

Request Example:cURL

curl -X POST https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/carts/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "addLineItem",
    "productId" : "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
    "variantId" : 1,
    "quantity" : 1
  } ]
}
DATA

Get Product Projection in Store by ID BETA

GET

https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/{id}

Gets the current or staged representation of a Product by its ID from the specified Store.

OAuth 2.0 Scopes:

view_products:{projectKey}, view_published_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`storeKey` String	`key` of the Store.
`id` String	`id` of the ProductProjection.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200ProductProjection

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Get Product Projection in Store by Key BETA

GET

https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/key={key}

Gets the current or staged representation of a Product by its key from the specified Store.

OAuth 2.0 Scopes:

view_products:{projectKey}, view_published_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`storeKey` String	`key` of the Store.
`key` String	`key` of the ProductProjection.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200ProductProjection

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-projections/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Query Product Selection Assignments in Store BETA

GET

https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-selection-assignments

Queries Product Selection assignments in a specific Store.

OAuth 2.0 Scopes:

view_product_selections:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`storeKey` String	`key` of the Store.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200ProductsInStorePagedQueryResponse

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/product-selection-assignments -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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

Stores

Representations.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}.css-e0dnmk{cursor:pointer;}

Store.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

StoreDraft.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

StorePagedQueryResponse.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

StoreReference.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

StoreResourceIdentifier.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

StoreKeyReference.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

ProductSelectionSetting BETA.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

ProductSelectionSettingDraft BETA.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get Store.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get Store by ID.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get Store by Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Query Stores.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Create Store.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update Store.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update Store by ID.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update Store by Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update actions.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Name.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Languages.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Distribution Channels.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Add Distribution Channel.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Remove Distribution Channel.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Supply Channels.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Add Supply Channel.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Remove Supply Channel.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Add Product Selection BETA.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Remove Product Selection BETA.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Product Selections BETA.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Change Product Selection Active BETA.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Custom Type.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set CustomField.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Delete Store.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Delete Store by ID.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Delete Store by Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Helpers in the HTTP and GraphQL APIs.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Query Carts in Store.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Create Cart in Store.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update Cart in Store.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get Product Projection in Store by ID BETA.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get Product Projection in Store by Key BETA.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Query Product Selection Assignments in Store BETA.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

GraphQL query fields.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

GraphQL mutations.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Representations

Store

StoreDraft

StorePagedQueryResponse

StoreReference

StoreResourceIdentifier

StoreKeyReference

ProductSelectionSetting BETA

ProductSelectionSettingDraft BETA

Get Store

Get Store by ID

Get Store by Key

Query Stores

Create Store

Update Store

Update Store by ID

Update Store by Key

Update actions

Set Name

Set Languages

Set Distribution Channels

Add Distribution Channel

Remove Distribution Channel

Set Supply Channels

Add Supply Channel

Remove Supply Channel

Add Product Selection BETA

Remove Product Selection BETA

Set Product Selections BETA

Change Product Selection Active BETA

Set Custom Type

Set CustomField

Delete Store

Delete Store by ID

Delete Store by Key

Helpers in the HTTP and GraphQL APIs

Query Carts in Store

Create Cart in Store

Update Cart in Store

Get Product Projection in Store by ID BETA

Get Product Projection in Store by Key BETA

Query Product Selection Assignments in Store BETA

GraphQL query fields

GraphQL mutations