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. |
roles ​Array of ChannelRoleEnum​ | Roles of the Channel. |
name ​ | Name of the Channel. |
description ​ | Description of the Channel. |
address ​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​ | GeoJSON geometry object encoding the geo location of the Channel. |
custom ​CustomFields​ | Custom Fields defined for the Channel. |
createdAt ​DateTime​ | Date and time (UTC) the Channel was initially created. |
createdBy ​BETACreatedBy​ | IDs and references that created the Channel. |
lastModifiedAt ​DateTime​ | Date and time (UTC) the Channel was last updated. |
lastModifiedBy ​BETA | IDs and references that last modified 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 |
name ​ | Name of the Channel. |
description ​ | Description of the Channel. |
address ​BaseAddress​ | Address where the Channel is located. |
geoLocation ​GeoJson​ | 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. 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 |
results ​Array of Channel​ | Channels matching the query. |
ChannelReference
id ​String​ | Unique identifier of the referenced Channel. |
typeId ​ | channel Type of referenced resource. |
obj ​Channel​ | Contains the representation of the expanded Channel. Only present in responses to requests with Reference Expansion for Channels. |
ChannelResourceIdentifier
ResourceIdentifier to a Channel. Either id
or key
is required. If both are set, an InvalidJsonInput error is returned.
id ​String​ | Unique identifier of the referenced Channel. Required if |
key ​String​ | User-defined unique identifier of the referenced Channel. Required if |
typeId ​ | channel Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource. |
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 Channel by ID
view_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/channels/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "ac390383-370f-43f8-a534-db1604cb96a8",
"key": "commercetools",
"version": 1,
"roles": ["InventorySupply"],
"createdAt": "2015-05-28T09:48:35.023Z",
"lastModifiedAt": "2015-05-28T09:48:35.023Z"
}
Get Channel by Key
view_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
key String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/channels/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "ac390383-370f-43f8-a534-db1604cb96a8",
"key": "commercetools",
"version": 1,
"roles": ["InventorySupply"],
"createdAt": "2015-05-28T09:48:35.023Z",
"lastModifiedAt": "2015-05-28T09:48:35.023Z"
}
Query Channels
view_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
where | 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 ​ | Number of results requested. Default: 20 ​ |
offset Int ​ | Number of elements skipped. Default: 0 ​ |
withTotal Boolean ​ | Controls the calculation of the total number of query results. Set to Default: true ​ |
var.<varName> String ​ | Predicate parameter values. The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/channels -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"limit": 20,
"offset": 0,
"count": 2,
"total": 2,
"results": [
{
"id": "ac390383-370f-43f8-a534-db1604cb96a8",
"key": "channel1",
"version": 1,
"roles": ["InventorySupply"],
"createdAt": "2015-05-28T09:48:35.023Z",
"lastModifiedAt": "2015-05-28T09:48:35.023Z"
},
{
"id": "51323ad2-89f2-4233-b9be-f15c049769c8",
"key": "channel2",
"version": 2,
"roles": ["InventorySupply"],
"createdAt": "2017-01-10T06:51:08.866Z",
"lastModifiedAt": "2017-01-10T06:51:08.924Z"
}
]
}
Check if Channel exists
Check if Channel exists by ID
Checks if a Channel exists for a given id
. Returns a 200 OK
status if the Channel exists or a 404 Not Found
otherwise.
view_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/channels/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Channel exists by Key
Checks if a Channel exists for a given key
. Returns a 200 OK
status if the Channel exists or a 404 Not Found
otherwise.
view_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
key String ​ |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/channels/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Channel exists by Query Predicate
Checks if a Channel exists for a given Query Predicate. Returns a 200 OK
status if any Channels match the Query Predicate or a 404 Not Found
otherwise.
view_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
where |
curl --head https://api.{region}.commercetools.com/{projectKey}/channels -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Create Channel
manage_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl 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
{
"id": "ac390383-370f-43f8-a534-db1604cb96a8",
"key": "commercetools",
"version": 1,
"roles": ["InventorySupply"],
"createdAt": "2015-05-28T09:48:35.023Z",
"lastModifiedAt": "2015-05-28T09:48:35.023Z"
}
Update Channel
Update Channel by ID
manage_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
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 ConcurrentModification error will be returned. |
actions ​Array of ChannelUpdateAction​ | Update actions to be performed on the Channel. |
application/json
curl 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
{
"id": "ac390383-370f-43f8-a534-db1604cb96a8",
"key": "commercetools",
"version": 2,
"name": {
"en": "New Name"
},
"roles": ["InventorySupply"],
"createdAt": "2015-05-28T09:48:35.023Z",
"lastModifiedAt": "2015-06-02T09:48:35.023Z"
}
Update Channel by Key
manage_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
key String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
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 ConcurrentModification error will be returned. |
actions ​Array of ChannelUpdateAction​ | Update actions to be performed on the Channel. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/channels/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeName",
"name" : {
"en" : "New Name"
}
} ]
}
DATA
{
"id": "ac390383-370f-43f8-a534-db1604cb96a8",
"key": "commercetools",
"version": 2,
"name": {
"en": "New Name"
},
"roles": ["InventorySupply"],
"createdAt": "2015-05-28T09:48:35.023Z",
"lastModifiedAt": "2015-06-02T09:48:35.023Z"
}
Update actions
Change Key
action ​String​ | "changeKey" |
key ​String​ | New value to set. Must not be empty. |
{
"action": "changeKey",
"key": "myNewChannelKey"
}
Change Name
action ​String​ | "changeName" |
name ​ | New value to set. Must not be empty. |
{
"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. |
{
"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 |
{
"action": "setRoles",
"roles": [
"ProductDistribution",
"Primary"
]
}
Add Roles
action ​String​ | "addRoles" |
roles ​Array of ChannelRoleEnum​ | Value to append to the array. |
{
"action": "addRoles",
"roles": [
"InventorySupply"
]
}
Remove Roles
action ​String​ | "removeRoles" |
roles ​Array of ChannelRoleEnum​ | Value to remove from the array. |
{
"action": "removeRoles",
"roles": [
"InventorySupply"
]
}
Set Address
action ​String​ | "setAddress" |
address ​BaseAddress​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setAddress",
"address": {
"key": "exampleKey",
"title": "My Address",
"salutation": "Mr.",
"firstName": "Example",
"lastName": "Person",
"streetName": "Example 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. |
{
"action": "setCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}
Set CustomField
action ​String​ | "setCustomField" |
name ​String​ | Name of the Custom Field. |
value ​ | If |
{
"action": "setCustomField",
"name": "exampleStringField",
"value": "TextString"
}
Set Custom Type in Address
action ​String​ | "setAddressCustomType" |
type ​ | Defines the Type that extends the |
fields ​ | Sets the Custom Fields fields for the |
{
"action": "setAddressCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "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 |
{
"action": "setAddressCustomField",
"name": "exampleStringField",
"value": "TextString"
}
Set GeoLocation
action ​String​ | "setGeoLocation" |
geoLocation ​GeoJson​ | Value to set. |
{
"action": "setGeoLocation",
"geoLocation": {
"type": "Point",
"coordinates": [
13.412119019109015,
52.50103330534661
]
}
}
Delete Channel
A Channel can only be deleted if it is not referenced by an InventoryEntry, a LineItem, a Store, a Price, a StandalonePrice, or a CartDiscountValueGiftLineItem.
Delete Channel by ID
Returns a ReferenceExists error if other resources reference the Channel to be deleted.
manage_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/channels/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "ac390383-370f-43f8-a534-db1604cb96a8",
"key": "commercetools",
"version": 1,
"roles": ["InventorySupply"],
"createdAt": "2015-05-28T09:48:35.023Z",
"lastModifiedAt": "2015-05-28T09:48:35.023Z"
}
Delete Channel by Key
Returns a ReferenceExists error if other resources reference the Channel to be deleted.
manage_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
key String ​ |
|
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/channels/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "ac390383-370f-43f8-a534-db1604cb96a8",
"key": "commercetools",
"version": 1,
"roles": ["InventorySupply"],
"createdAt": "2015-05-28T09:48:35.023Z",
"lastModifiedAt": "2015-05-28T09:48:35.023Z"
}