Stores

Representations

Store

• id - String
• version - Number
• key - String
  User-specific unique identifier for the store. The key is mandatory and immutable. It is used to reference the store.
• name - LocalizedString - Optional
  The name of the store
• languages - Array of Strings - Optional
  IETF language tag.
• distributionChannels - Set of Reference to a Channel with ProductDistribution ChannelRole
• supplyChannels - Set of Reference to a Channel with InventorySupply ChannelRole
• custom - CustomFields - Optional
• createdAt - DateTime
• lastModifiedAt - DateTime

StoreDraft

• key - String
  User-specific unique identifier for the store. The key is mandatory and immutable. It is used to reference the store.
• name - LocalizedString - Optional
  The name of the store
• languages - Array of Strings - Optional
  IETF language tag. Only languages defined in the project can be used.
• distributionChannels - Set of ResourceIdentifier of a Channel with ProductDistribution ChannelRole - Optional
• custom - CustomFieldsDraft - Optional
• supplyChannels - Set of ResourceIdentifier of Channels with InventorySupply ChannelRole - Optional

Get a Store

Get a Store by ID

Retrieves the representation of a store by its id.

Endpoint: /{projectKey}/stores/{id}
Method: GET
OAuth 2.0 Scopes: view_stores:{projectKey}
Response Representation: Store

Get a Store by Key

Retrieves the representation of a store by its key.

Endpoint: /{projectKey}/stores/key={key}
Method: GET
OAuth 2.0 Scopes: view_stores:{projectKey}
Response Representation: Store

Query Stores

Endpoint: /{projectKey}/stores
Method: GET
OAuth 2.0 Scopes: view_stores:{projectKey}
Response Representation: PagedQueryResult with results containing an array of Store
Query Parameters:

• where - Query Predicate - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - Number - Optional

Create a Store

Endpoint: /{projectKey}/stores
Method: POST
OAuth 2.0 Scopes: manage_stores:{projectKey}
Request Representation: StoreDraft
Response Representation: Store

Update Store

Update Store by ID

Endpoint: /{projectKey}/stores/{id}
Method: POST
OAuth 2.0 Scopes: manage_stores:{projectKey}
Response Representation: Store
Fields:

• version - Number - Required
  The expected version of the store on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the store.

Update Store by Key

Endpoint: /{projectKey}/stores/key={key}
Method: POST
OAuth 2.0 Scopes: manage_stores:{projectKey}
Response Representation: Store
Fields:

• version - Number - Required
  The expected version of the store on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the store.

Update actions

Set Name

• action - String - "setName"
• name - LocalizedString - Optional
  The updated name of the store

Set Languages

• action - String - "setLanguages"
• languages - Array of Strings - Optional
  IETF language tag. Only languages defined in the project can be used. An attempt to use other languages will fail with a ProjectNotConfiguredForLanguages error.

Set Distribution Channels

• action - String - "setDistributionChannels"
• distributionChannels - Set of ResourceIdentifier of a Channel with ProductDistribution ChannelRole - Optional
  If not defined, the store's distributionChannels are unset. An attempt to use Channel without the ProductDistribution ChannelRole will fail with a MissingRoleOnChannel error.

Add Distribution Channel

• action - String - "addDistributionChannel"
• distributionChannel - ResourceIdentifier of a Channel with ProductDistribution ChannelRole
  This action has no effect if given distribution channel is already present in a Store. An attempt to use Channel without the ProductDistribution ChannelRole will fail with a MissingRoleOnChannel error.

Remove Distribution Channel

• action - String - "removeDistributionChannel"
• distributionChannel - ResourceIdentifier of a Channel with ProductDistribution ChannelRole

Set Supply Channels

• action - String - "setSupplyChannels"
• supplyChannels - Set of ResourceIdentifier of a Channel with InventorySupply ChannelRole - Optional
  If not defined, the store's supplyChannels are unset. An attempt to use Channel without the InventorySupply ChannelRole will fail with a MissingRoleOnChannel error.

Add Supply Channel

• action - String - "addSupplyChannel"
• supplyChannel - ResourceIdentifier of a Channel with InventorySupply ChannelRole
  This action has no effect if given supply channel is already present in a Store. An attempt to use Channel without the InventorySupply ChannelRole will fail with a MissingRoleOnChannel error.

Remove Supply Channel

• action - String - "removeSupplyChannel"
• supplyChannel - ResourceIdentifier of a Channel with InventorySupply ChannelRole

Set Custom Type

This action sets, overwrites, or removes any existing custom type and fields for an existing store.

• action - String - "setCustomType"
• type - ResourceIdentifier of a Type - Optional
  If set, the custom type is reset to this value.
  If absent, the custom type and any existing custom fields are removed.
• fields - A valid JSON object, based on the FieldDefinitions of the Type - Optional
  Sets the custom field to this value.

Set CustomField

This action sets, overwrites, or removes any existing custom field for an existing store.

Delete Store

Delete Store by ID

Endpoint: /{projectKey}/stores/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_stores:{projectKey}
Query Parameters:

• version - Number - Required

Delete Store by Key

Endpoint: /{projectKey}/stores/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_stores:{projectKey}
Query Parameters:

• version - Number - Required

Helpers in the HTTP API and the GraphQL API

To access or modify carts, orders, and customers belonging to a store, some helpers are available both in the HTTP API and the GraphQL API. These can optionally also be used with the store-based OAuth permissions (for example manage_orders:project-key:store-key).

HTTP API endpoints

To access or modify resources belonging to a specific store, a different URL can be used. As an example, the following query will only return ids of carts that have been created in the store luxury-brand, and the total field counts only carts within that store:

GET /project/in-store/key=luxury-brand/carts

To create a cart in this store, you can use:

POST /project/in-store/key=luxury-brand/carts

The following example will only update the cart if it is in the luxury-brand store. Otherwise, a 404 error will be returned.

POST /project/in-store/key=luxury-brand/carts/{cart-id}

These can either be used with regular OAuth permissions (for example manage_orders:project-key) or with the store-based OAuth permissions (for example manage_orders:project-key:store-key). For these examples, the OAuth scope must contain either manage_orders:project-key or manage_orders:project-key:luxury-brand, otherwise an insufficient_scope error is returned.

For more information, see:

• Carts
• My Carts
• Orders
• My Orders

GraphQL query fields

The top-level fields inStore and inStores are available to only query resources belonging to the specified stores. As an example, the following query will only return ids of carts that have been created in the store luxury-brand, and the total field counts only carts within that store:

query {
  inStore(key: "luxury-brand") {
    carts {
      results {
        id
      }
      total
    }
  }
}

Similarly, inStores(keys: ["luxury-brand", "budget-brand"]) will perform the queries only within these two stores.

Both can either be used with regular OAuth permissions (for example manage_orders:project-key) or with the store-based OAuth permissions (for example manage_orders:project-key:store-key). For the inStores example, the OAuth scope must contain manage_orders:project-key:luxury-brand manage_orders:project-key:budget-brand, otherwise an insufficient_scope error is returned.

GraphQL mutations

Mutations on carts, orders, and customers have an optional argument called storeKey. In the following example, the cart is created in the store luxury-brand:

mutation {
  createCart(
    draft: {
      currency: "USD"
    }
    storeKey: "luxury-brand"
  )
  {
    id
  }
}

The following update to the cart is only performed if the cart is in the store luxury-brand:

mutation {
  updateCart(
    id: "123e4567-e89b-12d3-a456-426655440000"
    version: 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).