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

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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
name

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.

productSelectionsBETA

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

Custom fields for the Store.

createdAt

Date and time (UTC) the Store was initially created.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the Store was last updated.

lastModifiedByBETA

Present on resources created after 1 February 2019 except for events not tracked.

StoreDraft

key
String

User-defined unique and immutable identifier for the Store. Keys can only contain alphanumeric characters, underscores, and hyphens.

MinLength: 2MaxLength: 256Pattern: ^[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.

distributionChannels

ResourceIdentifier of a Channel with ProductDistribution ChannelRoleEnum.

supplyChannels

ResourceIdentifier of a Channel with InventorySupply ChannelRoleEnum.

productSelectionsBETA

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

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

id
String

Unique ID of the referenced Store.

typeId
String
"store"

References a Store.

obj

Contains the representation of the expanded Store. Only present in responses to requests with Reference Expansion for Stores.

StoreResourceIdentifier

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

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

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
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}'
200 Response Example: Storejson
{
"id" : "c2f93299-c967-44af-8c2a-d2220bf39eb2",
"version" : 1,
"key" : "random-key-12314",
"name" : {
"en" : "big store"
},
"languages" : [ ],
"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
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}'
200 Response Example: Storejson
{
"id" : "c2f93299-c967-44af-8c2a-d2220bf39eb2",
"version" : 1,
"key" : "random-key-12314",
"name" : {
"en" : "big store"
},
"languages" : [ ],
"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
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
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}'
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" : [ ],
"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" : [ ],
"distributionChannels" : [ ],
"supplyChannels" : [ ],
"productSelections" : [ ],
"createdAt" : "1973-01-01T00:00:00.001Z",
"lastModifiedAt" : "1973-01-01T00:00:00.001Z"
} ]
}

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
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
201 Response Example: Storejson
{
"id" : "c2f93299-c967-44af-8c2a-d2220bf39eb2",
"version" : 1,
"key" : "random-key-12314",
"name" : {
"en" : "big store"
},
"languages" : [ ],
"distributionChannels" : [ ],
"supplyChannels" : [ ],
"productSelections" : [ ],
"createdAt" : "1971-01-01T00:00:00.001Z",
"lastModifiedAt" : "1972-01-01T00:00:00.001Z"
}

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
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
200 Response Example: Storejson
{
"id" : "c2f93299-c967-44af-8c2a-d2220bf39eb2",
"version" : 1,
"key" : "random-key-12314",
"name" : {
"en" : "big store"
},
"languages" : [ ],
"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
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
200 Response Example: Storejson
{
"id" : "c2f93299-c967-44af-8c2a-d2220bf39eb2",
"version" : 1,
"key" : "random-key-12314",
"name" : {
"en" : "big store"
},
"languages" : [ ],
"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.

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

Set Languages

This update action produces the StoreLanguagesChanged Message.

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

This update action produces the StoreDistributionChannelsChanged Message.

action
String
"setDistributionChannels"
distributionChannels

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 update action produces the StoreDistributionChannelsChanged Message. It has no effect if a given distribution channel is already present in a Store.

action
String
"addDistributionChannel"
distributionChannel

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

This update action produces the StoreDistributionChannelsChanged Message.

action
String
"removeDistributionChannel"
distributionChannel

Value to remove. ResourceIdentifier of a Channel with the ProductDistribution ChannelRoleEnum.

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

Set Supply Channels

This update action produces the StoreSupplyChannelsChanged Message.

action
String
"setSupplyChannels"
supplyChannels

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 update action produces the StoreSupplyChannelsChanged Message. It has no effect if a given supply channel is already present in a Store.

action
String
"addSupplyChannel"
supplyChannel

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

This update action produces the StoreSupplyChannelsChanged Message.

action
String
"removeSupplyChannel"
supplyChannel

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

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

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

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

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

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.

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

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:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:

200Store

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" : [ ],
"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
The parameter can be passed multiple times.
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}'
200 Response Example: Storejson
{
"id" : "c2f93299-c967-44af-8c2a-d2220bf39eb2",
"version" : 1,
"key" : "random-key-12314",
"name" : {
"en" : "big store"
},
"languages" : [ ],
"distributionChannels" : [ ],
"supplyChannels" : [ ],
"productSelections" : [ ],
"createdAt" : "1971-01-01T00:00:00.001Z",
"lastModifiedAt" : "1972-01-01T00:00:00.001Z"
}

Helpers in the HTTP and GraphQL APIs

Product Selections and In-Store Product Projections, Carts, Orders, and Shopping Lists

Store's active Product Selection(s) form it's assortment. Or in other words a Product is considered available in a Store if it is part of least one active Product Selection of a Store.

When a Product is part of a Store's active Product Selection and has associated Variant Selection, it's In-Store representation - Product Projections, Carts, My Carts, Orders, My Orders, Shopping Lists, and My Shopping Lists, is transformed such that only selected Product Variants are present.

When a Store has two, or more, active Product Selection(s) that contain the same Product each but with different Variant Selections, Product's In-Store representation is resolved in following manner: All Product Variants that are included across Product Selections are kept, with the exception of ones that are excluded.

If Product's Variant Selection excludes all of the Product's Variants, the Product is considered as absent in the Store.

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. They can be used with the store-based OAuth permissions, such as manage_orders:project-key:store-key.

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.

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
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
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}'
200 Response Example: CartPagedQueryResponsejson
{
"limit" : 20,
"offset" : 0,
"count" : 2,
"total" : 2,
"results" : [ {
"type" : "Cart",
"id" : "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version" : 5,
"createdAt" : "2015-09-22T15:36:17.510Z",
"lastModifiedAt" : "2015-09-22T15:41:55.816Z",
"lineItems" : [ {
"id" : "b925a817-d5ad-48bb-a407-29ad8e0649b5",
"productId" : "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"name" : {
"en" : "SAPPHIRE"
},
"productType" : {
"typeId" : "product-type",
"id" : "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
"version" : 8
},
"productSlug" : {
"en" : "sapphire1421832124423"
},
"variant" : {
"id" : 1,
"sku" : "sku_SAPPHIRE_variant1_1421832124423",
"prices" : [ {
"value" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 2800
},
"id" : "8da659ef-9e54-447d-9c36-84912db1848f"
} ],
"images" : [ {
"url" : "https://www.commercetools.com/cli/data/252542005_1.jpg",
"dimensions" : {
"w" : 1400,
"h" : 1400
}
} ],
"attributes" : [ ],
"assets" : [ ]
},
"price" : {
"value" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 2800
},
"id" : "8da659ef-9e54-447d-9c36-84912db1848f"
},
"quantity" : 2,
"discountedPricePerQuantity" : [ ],
"state" : [ {
"quantity" : 2,
"state" : {
"typeId" : "state",
"id" : "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
} ],
"priceMode" : "Platform",
"lineItemMode" : "Standard",
"totalPrice" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 5600
},
"perMethodTaxRate" : [ ],
"taxedPricePortions" : [ ]
} ],
"cartState" : "Active",
"totalPrice" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 5600
},
"customLineItems" : [ ],
"discountCodes" : [ ],
"inventoryMode" : "None",
"taxMode" : "Platform",
"taxRoundingMode" : "HalfEven",
"taxCalculationMode" : "LineItemLevel",
"refusedGifts" : [ ],
"origin" : "Customer",
"shipping" : [ ],
"shippingMode" : "Single"
}, {
"type" : "Cart",
"id" : "668e5783-73c8-4f2d-91f4-3c90b872c700",
"version" : 3,
"createdAt" : "2015-10-07T07:33:05.894Z",
"lastModifiedAt" : "2015-10-07T07:33:06.070Z",
"lineItems" : [ {
"id" : "90dff06c-272e-47fa-b8de-923dce092474",
"productId" : "7b1203f4-66c0-438c-9a30-f4fb6be79bdf",
"name" : {
"de" : "WB ATHLETIC PANZER",
"en" : "WB ATHLETIC TANK"
},
"productType" : {
"typeId" : "product-type",
"id" : "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
"version" : 8
},
"productSlug" : {
"en" : "wb-athletic-tank1421832124574"
},
"variant" : {
"id" : 1,
"sku" : "sku_WB_ATHLETIC_TANK_variant1_1421832124574",
"prices" : [ {
"value" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 8400
},
"id" : "37696f7c-8260-4941-a921-68e6aa76b4a3"
} ],
"images" : [ {
"url" : "https://www.commercetools.com/cli/data/253265444_1.jpg",
"dimensions" : {
"w" : 1400,
"h" : 1400
}
} ],
"attributes" : [ ],
"assets" : [ ]
},
"price" : {
"value" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 8400
},
"id" : "37696f7c-8260-4941-a921-68e6aa76b4a3"
},
"quantity" : 1,
"discountedPricePerQuantity" : [ ],
"state" : [ {
"quantity" : 1,
"state" : {
"typeId" : "state",
"id" : "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
} ],
"priceMode" : "Platform",
"lineItemMode" : "Standard",
"totalPrice" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 8400
},
"custom" : {
"type" : {
"typeId" : "type",
"id" : "3ae9bcca-df23-443e-bd22-0c592f9694fa"
},
"fields" : {
"offer_name" : "SuperMax"
}
},
"perMethodTaxRate" : [ ],
"taxedPricePortions" : [ ]
} ],
"cartState" : "Active",
"totalPrice" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 8400
},
"country" : "DE",
"customLineItems" : [ ],
"discountCodes" : [ ],
"inventoryMode" : "None",
"taxMode" : "Platform",
"taxRoundingMode" : "HalfEven",
"taxCalculationMode" : "LineItemLevel",
"refusedGifts" : [ ],
"origin" : "Customer",
"shipping" : [ ],
"shippingMode" : "Single"
} ]
}

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
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",
"shipping" : [ ],
"customShipping" : [ ]
}
DATA
201 Response Example: Cartjson
{
"type" : "Cart",
"id" : "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"key" : "test-key",
"version" : 5,
"createdAt" : "2015-09-22T15:36:17.510Z",
"lastModifiedAt" : "2015-09-22T15:41:55.816Z",
"lineItems" : [ {
"id" : "b925a817-d5ad-48bb-a407-29ad8e0649b5",
"productId" : "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"name" : {
"en" : "SAPPHIRE"
},
"productType" : {
"typeId" : "product-type",
"id" : "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
"version" : 8
},
"productSlug" : {
"en" : "sapphire1421832124423"
},
"variant" : {
"id" : 1,
"sku" : "sku_SAPPHIRE_variant1_1421832124423",
"prices" : [ {
"value" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 2800
},
"id" : "8da659ef-9e54-447d-9c36-84912db1848f"
} ],
"images" : [ {
"url" : "https://www.commercetools.com/cli/data/252542005_1.jpg",
"dimensions" : {
"w" : 1400,
"h" : 1400
}
} ],
"attributes" : [ ],
"assets" : [ ]
},
"price" : {
"value" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 2800
},
"id" : "8da659ef-9e54-447d-9c36-84912db1848f"
},
"quantity" : 2,
"discountedPricePerQuantity" : [ ],
"state" : [ {
"quantity" : 2,
"state" : {
"typeId" : "state",
"id" : "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
} ],
"priceMode" : "Platform",
"lineItemMode" : "Standard",
"totalPrice" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 5600
},
"perMethodTaxRate" : [ ],
"taxedPricePortions" : [ ]
} ],
"store" : {
"typeId" : "store",
"key" : "test-key"
},
"cartState" : "Active",
"totalPrice" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 5600
},
"customLineItems" : [ ],
"discountCodes" : [ ],
"inventoryMode" : "None",
"taxMode" : "Platform",
"taxRoundingMode" : "HalfEven",
"taxCalculationMode" : "LineItemLevel",
"refusedGifts" : [ ],
"totalLineItemQuantity" : 2,
"origin" : "Customer",
"shipping" : [ ],
"shippingMode" : "Single"
}

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
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
200 Response Example: Cartjson
{
"type" : "Cart",
"id" : "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"key" : "test-key",
"version" : 5,
"createdAt" : "2015-09-22T15:36:17.510Z",
"lastModifiedAt" : "2015-09-22T15:41:55.816Z",
"lineItems" : [ {
"id" : "b925a817-d5ad-48bb-a407-29ad8e0649b5",
"productId" : "9f10dcfb-5cc9-4a18-843a-c07f7e22d01f",
"name" : {
"en" : "SAPPHIRE"
},
"productType" : {
"typeId" : "product-type",
"id" : "2543e1d8-4915-4f72-a3c9-1df9b1b0082d",
"version" : 8
},
"productSlug" : {
"en" : "sapphire1421832124423"
},
"variant" : {
"id" : 1,
"sku" : "sku_SAPPHIRE_variant1_1421832124423",
"prices" : [ {
"value" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 2800
},
"id" : "8da659ef-9e54-447d-9c36-84912db1848f"
} ],
"images" : [ {
"url" : "https://www.commercetools.com/cli/data/252542005_1.jpg",
"dimensions" : {
"w" : 1400,
"h" : 1400
}
} ],
"attributes" : [ ],
"assets" : [ ]
},
"price" : {
"value" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 2800
},
"id" : "8da659ef-9e54-447d-9c36-84912db1848f"
},
"quantity" : 2,
"discountedPricePerQuantity" : [ ],
"state" : [ {
"quantity" : 2,
"state" : {
"typeId" : "state",
"id" : "7c2e2694-aefe-43d7-888e-6a99514caaca"
}
} ],
"priceMode" : "Platform",
"lineItemMode" : "Standard",
"totalPrice" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 5600
},
"perMethodTaxRate" : [ ],
"taxedPricePortions" : [ ]
} ],
"store" : {
"typeId" : "store",
"key" : "test-key"
},
"cartState" : "Active",
"totalPrice" : {
"type" : "centPrecision",
"fractionDigits" : 2,
"currencyCode" : "EUR",
"centAmount" : 5600
},
"customLineItems" : [ ],
"discountCodes" : [ ],
"inventoryMode" : "None",
"taxMode" : "Platform",
"taxRoundingMode" : "HalfEven",
"taxCalculationMode" : "LineItemLevel",
"refusedGifts" : [ ],
"totalLineItemQuantity" : 2,
"origin" : "Customer",
"shipping" : [ ],
"shippingMode" : "Single"
}

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
Query parameters:
expand
The parameter can be passed multiple times.
priceCurrency
priceCountry

Use for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Use for locale-based projection.

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
The parameter can be passed multiple times.
priceCurrency
priceCountry

Use for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceCustomerGroup
String

id of an existing CustomerGroup used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

priceChannel
String

id of an existing Channel used for Price selection. Can only be used in conjunction with the priceCurrency parameter.

localeProjection

Use for locale-based projection.

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.

The response will include duplicate Products whenever more than one active Product Selection of the Store includes a Product. To make clear through which Product Selection a Product is available in the Store the response contains assignments including both the Product and the Product Selection. Only Products of Product Selections that are activated in Store will be returned.

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
The parameter can be passed multiple times.
limit
Int
offset
Int

Number of elements skipped.

withTotal
Boolean

By default, the response does not include the total field. Set to true to get the total number of query results included.

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}'
200 Response Example: ProductsInStorePagedQueryResponsejson
{
"limit" : 20,
"offset" : 0,
"count" : 1,
"results" : [ {
"productSelection" : {
"id" : "3a914b5c-4b87-42ce-998c-91e5aa7a329f",
"typeId" : "product-selection"
},
"product" : {
"id" : "d1c99e83-b9d4-48b2-9441-108c2a47009b",
"typeId" : "product"
}
} ]
}

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