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.

Learn more about Stores in our self-paced Stores and Channels module.

Representations

Store

StoreCountry

StoreDraft

StorePagedQueryResponse

StoreReference

StoreKeyReference

StoreResourceIdentifier

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_-]+$`
`name` LocalizedString	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: Leave empty if all Products in the Project should be available in this Store. If only `inactive` Product Selections with `IndividualExclusion` ProductSelectionMode are provided, all the Products are available in this Store. If all the Product Selections provided are `inactive` and there's at least a Product Selection of mode `Individual`, no Product is available in this Store. If at least an `active` Product Selection is provided, only `active` Product Selections are considered to compute the availlability in this Store. MaxItems: `100`
`custom` CustomFields	Custom fields for the Store.
`createdAt` DateTime	Date and time (UTC) the Store was initially created.
`createdBy`BETA CreatedBy	IDs and references that created the Store.
`lastModifiedAt` DateTime	Date and time (UTC) the Store was last updated.
`lastModifiedBy`BETA LastModifiedBy	IDs and references that last modified the Store.

StoreCountry

code

CountryCode

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` LocalizedString	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 `ProductDistribution` ChannelRoleEnum. MaxItems: `100`
`supplyChannels` Array of ChannelResourceIdentifier	ResourceIdentifier of a Channel with `InventorySupply` ChannelRoleEnum. MaxItems: `100`
`productSelections` Array of ProductSelectionSettingDraft	Controls availability of Products for this Store via active/inactive Product Selections: Leave empty if all Products in the Project should be available in this Store. If only `inactive` Product Selections with `IndividualExclusion` ProductSelectionMode are provided, all the Products are available in this Store. If all the Product Selections provided are `inactive` and there's at least a Product Selection of mode `Individual`, no Product is available in this Store. If at least an `active` Product Selection is provided, only `active` Product Selections are considered to compute the availability in this Store. MaxItems: `100`
`custom` CustomFieldsDraft	Custom fields for the Store.

StorePagedQueryResponse

PagedQueryResult with results containing an array of Store.

`limit` Int	Number of results requested. Default: `20`Minimum: `0`Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0`Maximum: `10000`
`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` ReferenceTypeId	`store` Type of referenced resource.
`obj` Store	Contains the representation of the expanded Store. Only present in responses to requests with Reference Expansion for Stores.

StoreKeyReference

KeyReference to a Store.

`key` String	Unique and immutable key of the referenced Store.
`typeId` ReferenceTypeId	`store` Type of referenced resource.

StoreResourceIdentifier

ResourceIdentifier to a Store. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

`id` String	Unique ID of the referenced Store. Required if `key` is absent.
`key` String	Unique key of the referenced Store. Required if `id` is absent.
`typeId` ReferenceTypeId	`store` Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

ProductSelectionSetting

`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

`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:

200

Store

asapplication/json

Request Example:cURL

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

200 Response Example: Storejson

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

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:

200

Store

asapplication/json

Request Example:cURL

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

200 Response Example: Storejson

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

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.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested. Default: `20` Minimum: `0` Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0` Maximum: `10000`
`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. Default: `true`
`var.<varName>` String	Predicate parameter values. The parameter can be passed multiple times.

Response:

200

StorePagedQueryResponse

asapplication/json

Request Example:cURL

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

200 Response Example: StorePagedQueryResponsejson

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

HEAD

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

Checks if a Store exists with the provided id. Returns a 200 status if the Store exists, or a 404 status otherwise.

OAuth 2.0 Scopes:

view_states:{projectKey}

Path parameters:

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

Response:

200

Request Example:cURL

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

Check if Store exists by Key

HEAD

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

Checks if a Store exists with the provided key. Returns a 200 status if the Store exists, or a 404 status otherwise.

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.

Response:

200

Request Example:cURL

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

Check if Store exists by Query Predicate

HEAD

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

Checks if one or more Stores exist for the provided query predicate. Returns a 200 status if any Stores match the query predicate, or a 404 status otherwise.

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

Query Predicates on Stores are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.

Response:

200

Request Example:cURL

curl --head 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:StoreDraftasapplication/json

Response:

201

Store

asapplication/json

Request Example:cURL

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

201 Response Example: Storejson

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

ProjectNotConfiguredForLanguages

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:

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.

Response:

200

Store

asapplication/json

Request Example:cURL

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

200 Response Example: Storejson

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

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:

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.

Response:

200

Store

asapplication/json

Request Example:cURL

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

200 Response Example: Storejson

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

This update action produces the StoreNameSet Message.

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

Example: json

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

Example: json

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

Set Countries

This update action produces the StoreCountriesChanged Message.

`action` String	`"setCountries"`
`countries` Array of StoreCountry	New value to set.

Example: json

{
  "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` StoreCountry	Value to append to `countries`.

Example: json

{
  "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` StoreCountry	Value to remove from `countries`.

Example: json

{
  "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 `distributionChannels` are unset. MaxItems: `100`

Example: json

{
  "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` ChannelResourceIdentifier	Value to append.

Example: json

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

Remove Distribution Channel

This update action produces the StoreDistributionChannelsChanged Message.

`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

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 `supplyChannels` are unset. MaxItems: `100`

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.

Adding a supply channel produces the StoreSupplyChannelsChanged Message.

Adding a Channel without the InventorySupply ChannelRoleEnum returns a MissingRoleOnChannel error.

`action` String	`"addSupplyChannel"`
`supplyChannel` ChannelResourceIdentifier	Value to append.

Example: json

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

Remove Supply Channel

This update action produces the StoreSupplyChannelsChanged Message.

`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

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.

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

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. MaxItems: `100`

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

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` 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": {
    "exampleStringField": "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. Removing a field that does not exist returns an InvalidOperation error. If `value` is provided, it is set for the field defined by `name`.

Example: json

{
  "action": "setCustomField",
  "name": "exampleStringField",
  "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:

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

Response:

200

Store

asapplication/json

Request Example:cURL

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

200 Response Example: Storejson

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

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:

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

Response:

200

Store

asapplication/json

Request Example:cURL

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

200 Response Example: Storejson

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

Resources	API methods (link text shortened for better readability)
Business Units B2B	Get, Query, Create, Update, Delete
Carts	Get, Query, Create, Replicate, Update, Delete
My Carts BETA	Get, Get active Cart, Query, Create, Update, Delete
Cart Discounts	Get, Query, Create, Update, Delete
Customers	Get, Query, Create, Update, Change password, Authenticate, Get by password token, Reset password, Get by email token, Verify email, Delete
My Customers BETA	Get, Create, Update, Change password, Authenticate, Reset password, Verify email, Delete
Orders	Get by ID, Query, Create from Cart, Create from Quote, Update by ID, Delete by ID Get by OrderNumber, Update by OrderNumber, Delete by OrderNumber
My Orders BETA	Get by ID, Query, Create from Cart
Product Projections	Get
Product Tailoring	Get by Product Key, Get by Product ID, Query, Create , Update by Product Key , Update by Product ID, Delete by Product Key , Delete by Product ID
Quotes	Get, Query, Exists, Create, Update, Delete
Quote Requests	Get, Query, Exists, Create, Update, Delete
Shipping Methods	Get for a Cart
Shopping Lists	Get, Query, Create, Update, Delete
Staged Quotes	Get, Query, Exists, Create, Update, Delete
My Shopping Lists BETA	Get, Query, Create, Update, Delete

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: 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-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Store.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

StoreCountry.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

StoreDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

StorePagedQueryResponse.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

StoreReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

StoreKeyReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

StoreResourceIdentifier.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

ProductSelectionSetting.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

ProductSelectionSettingDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get Store.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get Store by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get Store by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Query Stores.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if Store exists.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if Store exists by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if Store exists by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if Store exists by Query Predicate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Create Store.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update Store.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update Store by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update Store by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update actions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Name.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Languages.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Countries.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Add Country.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Remove Country.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Distribution Channels.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Add Distribution Channel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Remove Distribution Channel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Supply Channels.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Add Supply Channel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Remove Supply Channel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Add Product Selection.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Remove Product Selection.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Product Selections.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Change Product Selection Active.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Custom Type.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set CustomField.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete Store.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete Store by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete Store by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Helpers in the HTTP and GraphQL APIs.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

In-Store representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Products available in Store.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

GraphQL query fields.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

GraphQL mutations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Representations

Store

StoreCountry

StoreDraft

StorePagedQueryResponse

StoreReference

StoreKeyReference

StoreResourceIdentifier

ProductSelectionSetting

ProductSelectionSettingDraft

Get Store

Get Store by ID

Get Store by Key

Query Stores

Check if Store exists

Check if Store exists by ID

Check if Store exists by Key

Check if Store exists by Query Predicate

Create Store

Update Store

Update Store by ID

Update Store by Key

Update actions

Set Name

Set Languages

Set Countries

Add Country

Remove Country

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

Delete Store

Delete Store by ID

Delete Store by Key

Helpers in the HTTP and GraphQL APIs

In-Store representations

Products available in Store

GraphQL query fields

GraphQL mutations