Channels

Channels represent a source or destination of different entities. They can be used to model warehouses or stores.

Channels are used across the different APIs in commercetools Composable Commerce to connect different entities (like inventory or price) to some specific source or destination of entities. For example, inventory may be connected to a supply channel that would describe from which supplier a stock comes from. Price may also have connection to the channel. In this case, you can save the inventory pricing information from the specific channel into the system. Similarly, after the disposition process, line items can get supply channel information that would uniquely identify inventory entries that should be reserved.

Representations

Channel

id
String

Unique identifier of the Channel.

version
Int

Current version of the Channel.

key
String

User-defined unique identifier of the Channel.

createdAt
DateTime

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

createdByBETA

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

lastModifiedAt

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

lastModifiedByBETA

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

roles
Array of ChannelRoleEnum

Roles of the Channel.

name

Name of the Channel.

description

Description of the Channel.

address

Address where the Channel is located (for example, if the Channel is a physical store).

reviewRatingStatistics

Statistics about the review ratings taken into account for the Channel.

geoLocation

GeoJSON geometry object encoding the geo location of the Channel.

custom

Custom Fields defined for the Channel.

ChannelDraft

key
String

User-defined unique identifier for the Channel.

roles
Array of ChannelRoleEnum

Roles of the Channel. Each channel must have at least one role. If not specified, then InventorySupply is assigned by default.

name

Name of the Channel.

description

Description of the Channel.

address

Address where the Channel is located.

geoLocation

GeoJSON geometry object encoding the geo location of the Channel. Currently, only the Point type is supported.

custom

Custom fields defined for the Channel.

ChannelPagedQueryResponse

PagedQueryResult with results containing an array of Channel.

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 Channel

Channels matching the query.

ChannelReference

id
String

Unique identifier of the referenced Channel.

typeId
String
"channel"

References a Channel.

obj

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

ChannelResourceIdentifier

id
String

Unique identifier of the referenced Channel. Either id or key is required.

key
String

User-defined unique identifier of the referenced Channel. Either id or key is required.

typeId
String
"channel"

References a Channel.

ChannelRoleEnum

Describes the purpose and type of the Channel. A Channel can have one or more roles.

InventorySupply

Channel can be used to track inventory entries (for example, Channels with this role can be treated as warehouses).

ProductDistribution

Channel can be used to expose Products to a specific distribution Channel. The Channel can be used by a Cart to select a Product Price.

OrderExport

Channel can be used to track order export activities.

OrderImport

Channel can be used to track order import activities.

Primary

This role can be combined with the other roles (for example, with InventorySupply). If used, the Channel is considered as the primary or main channel among Channels of the same type.

Get Channel

GET
https://api.{region}.commercetools.com/{projectKey}/channels/{id}
OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Channel.

Query parameters:
expand
The parameter can be passed multiple times.
Response:

200Channel

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

Query Channels

GET
https://api.{region}.commercetools.com/{projectKey}/channels
OAuth 2.0 Scopes:
view_products:{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:

200ChannelPagedQueryResponse

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

Create Channel

POST
https://api.{region}.commercetools.com/{projectKey}/channels
OAuth 2.0 Scopes:
manage_products:{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:ChannelDraft
Response:

201Channel

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/channels -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"key" : "commercetools",
"roles" : [ "InventorySupply" ]
}
DATA

Update Channel

POST
https://api.{region}.commercetools.com/{projectKey}/channels/{id}
OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Channel.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
version
Int

Expected version of the Channel on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict error will be returned.

actions

Update actions to be performed on the Channel.

Response:

200Channel

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/channels/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeName",
"name" : {
"en" : "New Name"
}
} ]
}
DATA

Update actions

Change Key

key
String

New value to set. Must not be empty.

action
String
"changeKey"
Example: json
{
"action" : "changeKey",
"key" : "myNewChannelKey"
}

Change Name

action
String
"changeName"
name

New value to set. Must not be empty.

Example: json
{
"action" : "changeName",
"name" : {
"en" : "new Channel Name EN",
"de" : "new Channel Name DE"
}
}

Change Description

action
String
"changeDescription"
description

New value to set. Must not be empty.

Example: json
{
"action" : "changeDescription",
"description" : {
"en" : "new Description EN",
"de" : "new Description DE"
}
}

Set Roles

action
String
"setRoles"
roles
Array of ChannelRoleEnum

Value to set. If not specified, then InventorySupply is assigned by default.

Example: json
{
"action" : "setRoles",
"roles" : [ "ProductDistribution", "Primary" ]
}

Add Roles

action
String
"addRoles"
roles
Array of ChannelRoleEnum

Value to append to the array.

Example: json
{
"action" : "addRoles",
"roles" : [ "InventorySupply" ]
}

Remove Roles

action
String
"removeRoles"
roles
Array of ChannelRoleEnum

Value to remove from the array.

Example: json
{
"action" : "removeRoles",
"roles" : [ "InventorySupply" ]
}

Set Address

action
String
"setAddress"
address

Value to set. If empty, any existing value will be removed.

Example: json
{
"action" : "setAddress",
"address" : {
"key" : "exampleKey",
"title" : "My Address",
"salutation" : "Mr.",
"firstName" : "Example",
"lastName" : "Person",
"streetName" : "Examplary Street",
"streetNumber" : "4711",
"additionalStreetInfo" : "Backhouse",
"postalCode" : "80933",
"city" : "Exemplary City",
"region" : "Exemplary Region",
"state" : "Exemplary State",
"country" : "DE",
"company" : "My Company Name",
"department" : "Sales",
"building" : "Hightower 1",
"apartment" : "247",
"pOBox" : "2471",
"phone" : "+49 89 12345678",
"mobile" : "+49 171 2345678",
"email" : "email@example.com",
"fax" : "+49 89 12345679",
"additionalAddressInfo" : "no additional Info",
"externalId" : "Information not needed"
}
}

Set Custom Type

action
String
"setCustomType"
type

Defines the Type that extends the Channel with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Channel.

fields

Sets the Custom Fields fields for the Channel.

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

Set CustomType in Address

action
String
"setAddressCustomType"
type

Defines the Type that extends the address with Custom Fields. If absent, any existing Type and Custom Fields are removed from the address.

fields

Sets the Custom Fields fields for the address.

Example: json
{
"action" : "setAddressCustomType",
"type" : {
"id" : "{{type-id}}",
"typeId" : "type"
},
"fields" : {
"examplaryStringTypeField" : "TextString"
}
}

Set CustomField in Address

action
String
"setAddressCustomField"
name
String

Name of the Custom Field.

value

Specifies the format of the value of the Custom Field defined by name. 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.

Example: json
{
"action" : "setAddressCustomField",
"name" : "ExamplaryStringTypeField",
"value" : "TextString"
}

Set GeoLocation

action
String
"setGeoLocation"
geoLocation

Value to set.

Example: json
{
"action" : "setGeoLocation",
"geoLocation" : {
"type" : "Point",
"coordinates" : [ 48.163569, 11.558663 ]
}
}

Delete Channel

DELETE
https://api.{region}.commercetools.com/{projectKey}/channels/{id}
OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Channel.

Query parameters:
expand
The parameter can be passed multiple times.
version
Int

Last seen version of the resource.

Response:

200Channel

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