Channels
Channels represent a source or destination of different entities. They can be used to model warehouses or stores.
Channels are used in different parts of the commercetools platform to connect different entities (like inventory or price) to some specific source or destination of entities. For example inventory may have connection to supply channel which would describe from which supplier this stock comes from. Price may also have connection to the channel. In this case you can save pricing information of inventory that comes from specific channel into the system. Similarly after the disposition process, line items can get supply channel information which would unique identify inventory entries that should be reserved.
Representations
Channel
id
- String
The unique ID of the channel.key
- String, unique within the project
Any arbitrary string key that uniquely identifies this channel within the project.version
- NumbercreatedAt
- DateTimecreatedBy
- CreatedBy BETA
Present on resources created after 2019-02-01 except for events not tracked.lastModifiedAt
- DateTimelastModifiedBy
- LastModifiedBy BETA
Present on resources updated after 2019-02-01 except for events not tracked.roles
- Set of ChannelRole values
The roles of this channel. Each channel must have at least one role.name
- LocalizedString - Optional
A human-readable name of the channel.description
- LocalizedString - Optional
A human-readable description of the channel.address
- Address - Optional
The address where this channel is located (for example if the channel is a physical store).reviewRatingStatistics
- ReviewRatingStatistics - Optional
Statistics about the review ratings taken into account for this channel.custom
- CustomFields - OptionalgeoLocation
- GeoJSON Geometry - Optional
A GeoJSON geometry object encoding the geo location of the channel.
ChannelDraft
key
- String - Requiredroles
- Set of ChannelRole values - Optional
If not specified, then channel will get InventorySupply role by defaultname
- LocalizedString - Optionaldescription
- LocalizedString - Optionaladdress
- Address - Optionalcustom
- CustomFieldsDraft - Optional
The custom fields.geoLocation
- GeoJSON Geometry - Optional
ChannelRoleEnum
ChannelRole enum describes the purpose and the type of this channel. Each channel can have one or more of following roles:
InventorySupply
- Role tells that this channel can be used to track inventory entries (for example channels with this role can be treated as warehouses).ProductDistribution
- Role tells that this channel can be used to expose products to a specific distribution channel. It can be used by the cart toselect a product price.OrderExport
- Role tells that this channel can be used to track order export activities.OrderImport
- Role tells that this channel can be used to track order import activities.Primary
- This role can be combined with some other roles (for example withInventorySupply
) to represent the fact that this particular channel is the primary/master channel among the channels of the same type.
Query Channels
Endpoint: /{projectKey}/channels
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with the results
array of Channel
Query Parameters:
where
- Query Predicate - Optionalsort
- Sort - Optionalexpand
- Expansion - Optionallimit
- Number - Optionaloffset
- Number - Optional
Get Channel by ID
Endpoint: /{projectKey}/channels/{id}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: Channel
Create a Channel
Endpoint: /{projectKey}/channels
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Request Representation: ChannelDraft
Response Representation: Channel
Update Channel
Endpoint: /{projectKey}/channels/{id}
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Response Representation: Channel
Fields:
version
- Number - Required
The 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 will be returned.actions
- Array of UpdateAction - Required
The list of update actions to be performed on the channel.
Update Actions
Change Key
action
- String -"changeKey"
key
- String
Change Name
action
- String -"changeName"
name
- LocalizedString
Change Description
action
- String -"changeDescription"
description
- LocalizedString
Set Roles
action
- String -"setRoles"
roles
- Set of ChannelRole values
Add Roles
action
- String -"addRoles"
roles
- Set of ChannelRole values
Remove Roles
action
- String -"removeRoles"
roles
- Set of ChannelRole values
Set Address
action
- String -"setAddress"
address
- Address - Optional
Set Custom Type
This action sets or removes the custom type for an existing channel. If present, this action overwrites any existing custom type and fields.
action
- String -"setCustomType"
type
- ResourceIdentifier to a Type - Optional
If absent, the custom type and any existing custom fields are removed.fields
- * - Optional
A valid JSON object, based on the FieldDefinitions of the Type. Sets the custom fields to this value.
Set CustomField
action
- String -"setCustomField"
name
- String - Requiredvalue
- Value - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. Ifvalue
is provided, set thevalue
of the field defined by thename
.
Set GeoLocation
action
- String -"setGeoLocation"
geoLocation
- GeoJSON Geometry - Optional
Delete Channel
This request deletes channel only if it's not referenced by other entities like inventory or LineItem.
Endpoint: /{projectKey}/channels/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_products:{projectKey}
Query Parameters:
version
- Number - Required