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.
  • version - Number
  • createdAt - DateTime
  • lastModifiedAt - DateTime
  • key - String, unique within the project
    Any arbitrary string key that uniquely identifies this channel within the project.
  • 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 (e.g. if the channel is a physical store).
  • reviewRatingStatistics - ReviewRatingStatistics - Optional
    Statistics about the review ratings taken into account for this channel.
  • custom - CustomFields - Optional
  • geoLocation - GeoJSON Geometry - Optional
    A GeoJSON geometry object encoding the geo location of the channel.

ChannelDraft

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. (e.g. 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 to select 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 (e.g. with InventorySupply) 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
OAuth2 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with the results array of Channel
Query Parameters:

Get Channel by ID

Endpoint: /{projectKey}/channels/{id}
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: Channel

Create a Channel

Endpoint: /{projectKey}/channels
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Request Representation: ChannelDraft
Response Representation: Channel

Update Channel

Endpoint: /{projectKey}/channels/{id}
Method: POST
OAuth2 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
Please find below the individual update actions provided on this endpoint.


Change Key

  • action - String - "changeKey"
  • key - String

Change Name

Change Description

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.

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

This action overwrites any existing custom type and fields.

Set CustomField

Set GeoLocation

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
OAuth2 Scopes: manage_products:{projectKey} Query Parameters:

  • version - Number - Required