Documentation

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 - Number
  • createdAt - DateTime
  • createdBy - CreatedBy BETA
    Present on resources created after 2019-02-01 except for events not tracked.
  • lastModifiedAt - DateTime
  • lastModifiedBy - 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 - 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 (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 results containing an array of Channel
Query Parameters:

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

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 - AddressDraft - 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 - Required
  • value - Value - Optional
    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, set the value of the field defined by the name.

Set CustomType in Address

This action sets and removes the Custom Type for an existing Address. This action overwrites all existing Custom Type and Fields in an Address.

  • action - String - "setAddressCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If absent, the custom type and any existing custom fields are removed from the address.
  • fields - * - Optional
    A valid JSON object, based on the FieldDefinitions of the Type. Sets the custom fields to this value.

Set CustomField in Address

This action sets, overwrites, or removes the custom field for an existing customer Address

  • action - String - "setAddressCustomField"
  • name - String - Required
    The name of the Custom Field to set
  • value - Value - Optional
    Specifies the format of the value of the Custom Field defined by name. If value is absent or null, the field specified by name, if it exists, is removed. Trying to remove a field that does not exist will fail with an InvalidOperation error.

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

  • version - Number - Required