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.

Learn more about Channels in our self-paced Stores and Channels module.

Representations

Channel

ChannelDraft

ChannelPagedQueryResponse

ChannelReference

ChannelKeyReference

ChannelResourceIdentifier

ChannelRoleEnum

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` LocalizedString	Name of the Channel.
`description` LocalizedString	Description of the Channel.
`address` Address	Address where the Channel is located (for example, if the Channel is a physical store).
`reviewRatingStatistics` 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`BETA CreatedBy	IDs and references that created the Channel.
`lastModifiedAt` DateTime	Date and time (UTC) the Channel was last updated.
`lastModifiedBy`BETA LastModifiedBy	IDs and references that last modified the Channel.

Example: json

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "createdAt": "2025-10-25T14:30:45.123Z",
  "lastModifiedAt": "2025-10-25T14:30:45.123Z",
  "key": "distribution-channel-us",
  "roles": [
    "ProductDistribution",
    "InventorySupply"
  ],
  "name": {
    "en-US": "US Distribution Channel",
    "de-DE": "US-Vertriebskanal",
    "fr-FR": "Canal de distribution américain",
    "es-ES": "Canal de distribución de EE. UU."
  },
  "description": {
    "en-US": "Primary distribution channel for United States market",
    "de-DE": "Primärer Vertriebskanal für den US-Markt",
    "fr-FR": "Canal de distribution principal pour le marché américain",
    "es-ES": "Canal de distribución principal para el mercado estadounidense"
  },
  "address": {
    "id": "address-1",
    "key": "us-warehouse-address",
    "country": "US",
    "firstName": "John",
    "lastName": "Smith",
    "streetName": "Commerce Street",
    "streetNumber": "123",
    "postalCode": "94105",
    "city": "San Francisco",
    "state": "California",
    "phone": "+14155551234",
    "email": "warehouse@example.com"
  },
  "geoLocation": {
    "type": "Point",
    "coordinates": [
      -122.4194,
      37.7749
    ]
  }
}

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` LocalizedString	Name of the Channel.
`description` LocalizedString	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` CustomFieldsDraft	Custom fields defined for the Channel.

Example: json

{
  "key": "distribution-channel-us",
  "roles": [
    "ProductDistribution",
    "InventorySupply"
  ],
  "name": {
    "en-US": "US Distribution Channel",
    "de-DE": "US-Vertriebskanal",
    "fr-FR": "Canal de distribution américain",
    "es-ES": "Canal de distribución de EE. UU."
  },
  "description": {
    "en-US": "Primary distribution channel for United States market",
    "de-DE": "Primärer Vertriebskanal für den US-Markt",
    "fr-FR": "Canal de distribution principal pour le marché américain",
    "es-ES": "Canal de distribución principal para el mercado estadounidense"
  },
  "address": {
    "key": "us-warehouse-address",
    "country": "US",
    "firstName": "John",
    "lastName": "Smith",
    "streetName": "Commerce Street",
    "streetNumber": "123",
    "postalCode": "94105",
    "city": "San Francisco",
    "state": "California",
    "phone": "+14155551234",
    "email": "warehouse@example.com"
  },
  "geoLocation": {
    "type": "Point",
    "coordinates": [
      -122.4194,
      37.7749
    ]
  }
}

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

Example: json

{
  "limit": 20,
  "offset": 0,
  "count": 2,
  "total": 2,
  "results": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "createdAt": "2025-10-25T14:30:45.123Z",
      "lastModifiedAt": "2025-10-25T14:30:45.123Z",
      "key": "distribution-channel-us",
      "roles": [
        "ProductDistribution",
        "InventorySupply"
      ],
      "name": {
        "en-US": "US Distribution Channel",
        "de-DE": "US-Vertriebskanal",
        "fr-FR": "Canal de distribution américain",
        "es-ES": "Canal de distribución de EE. UU."
      },
      "description": {
        "en-US": "Primary distribution channel for United States market",
        "de-DE": "Primärer Vertriebskanal für den US-Markt",
        "fr-FR": "Canal de distribution principal pour le marché américain",
        "es-ES": "Canal de distribución principal para el mercado estadounidense"
      },
      "address": {
        "id": "address-1",
        "key": "us-warehouse-address",
        "country": "US",
        "firstName": "John",
        "lastName": "Smith",
        "streetName": "Commerce Street",
        "streetNumber": "123",
        "postalCode": "94105",
        "city": "San Francisco",
        "state": "California",
        "phone": "+14155551234",
        "email": "warehouse@example.com"
      },
      "geoLocation": {
        "type": "Point",
        "coordinates": [
          -122.4194,
          37.7749
        ]
      }
    },
    {
      "id": "8c7e0b2a-45f3-4d8e-9a1b-c2f4e6d8a9b0",
      "version": 2,
      "createdAt": "2025-10-20T09:15:30.456Z",
      "lastModifiedAt": "2025-10-28T11:20:45.789Z",
      "key": "distribution-channel-eu",
      "roles": [
        "ProductDistribution"
      ],
      "name": {
        "en-US": "EU Distribution Channel",
        "de-DE": "EU-Vertriebskanal",
        "fr-FR": "Canal de distribution européen",
        "es-ES": "Canal de distribución de la UE"
      },
      "description": {
        "en-US": "Main distribution channel for European market",
        "de-DE": "Hauptvertriebskanal für den europäischen Markt",
        "fr-FR": "Canal de distribution principal pour le marché européen",
        "es-ES": "Canal de distribución principal para el mercado europeo"
      },
      "address": {
        "id": "address-2",
        "key": "eu-warehouse-address",
        "country": "DE",
        "firstName": "Anna",
        "lastName": "Müller",
        "streetName": "Hauptstraße",
        "streetNumber": "45",
        "postalCode": "10115",
        "city": "Berlin",
        "phone": "+493012345678",
        "email": "warehouse-eu@example.com"
      }
    }
  ]
}

ChannelReference

Reference to a Channel.

`id` String	Unique identifier of the referenced Channel.
`typeId` ReferenceTypeId	`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.

Example: json

{
  "typeId": "channel",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

ChannelKeyReference

Used by the Import API to identify a Channel.

`key` String	User-defined unique identifier of the referenced Channel.
`typeId` ReferenceType	`channel` Type of referenced resource.

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` is absent.
`key` String	User-defined unique identifier of the referenced Channel. Required if `id` is absent.
`typeId` ReferenceTypeId	`channel` Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

Example: json

{
  "typeId": "channel",
  "key": "distribution-channel-us"
}

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

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

Expansion

The parameter can be passed multiple times.

Response:

200

Channel

application/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/channels/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: Channeljson

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "createdAt": "2025-10-25T14:30:45.123Z",
  "lastModifiedAt": "2025-10-25T14:30:45.123Z",
  "key": "distribution-channel-us",
  "roles": ["ProductDistribution", "InventorySupply"],
  "name": {
    "en-US": "US Distribution Channel",
    "de-DE": "US-Vertriebskanal",
    "fr-FR": "Canal de distribution américain",
    "es-ES": "Canal de distribución de EE. UU."
  },
  "description": {
    "en-US": "Primary distribution channel for United States market",
    "de-DE": "Primärer Vertriebskanal für den US-Markt",
    "fr-FR": "Canal de distribution principal pour le marché américain",
    "es-ES": "Canal de distribución principal para el mercado estadounidense"
  },
  "address": {
    "id": "address-1",
    "key": "us-warehouse-address",
    "country": "US",
    "firstName": "John",
    "lastName": "Smith",
    "streetName": "Commerce Street",
    "streetNumber": "123",
    "postalCode": "94105",
    "city": "San Francisco",
    "state": "California",
    "phone": "+14155551234",
    "email": "warehouse@example.com"
  },
  "geoLocation": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  }
}

Get Channel by Key

GET

https://api.{region}.commercetools.com/{projectKey}/channels/key={key}

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the Channel.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200

Channel

application/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/channels/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: Channeljson

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "createdAt": "2025-10-25T14:30:45.123Z",
  "lastModifiedAt": "2025-10-25T14:30:45.123Z",
  "key": "distribution-channel-us",
  "roles": ["ProductDistribution", "InventorySupply"],
  "name": {
    "en-US": "US Distribution Channel",
    "de-DE": "US-Vertriebskanal",
    "fr-FR": "Canal de distribution américain",
    "es-ES": "Canal de distribución de EE. UU."
  },
  "description": {
    "en-US": "Primary distribution channel for United States market",
    "de-DE": "Primärer Vertriebskanal für den US-Markt",
    "fr-FR": "Canal de distribution principal pour le marché américain",
    "es-ES": "Canal de distribución principal para el mercado estadounidense"
  },
  "address": {
    "id": "address-1",
    "key": "us-warehouse-address",
    "country": "US",
    "firstName": "John",
    "lastName": "Smith",
    "streetName": "Commerce Street",
    "streetNumber": "123",
    "postalCode": "94105",
    "city": "San Francisco",
    "state": "California",
    "phone": "+14155551234",
    "email": "warehouse@example.com"
  },
  "geoLocation": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  }
}

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` QueryPredicate	The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested. Default: `20` Minimum: `0` Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0` Maximum: `10000`
`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. Default: `true`
`var.<varName>` String	Predicate parameter values. The parameter can be passed multiple times.

Response:

200

ChannelPagedQueryResponse

application/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/channels -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: ChannelPagedQueryResponsejson

{
  "limit": 20,
  "offset": 0,
  "count": 2,
  "total": 2,
  "results": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "createdAt": "2025-10-25T14:30:45.123Z",
      "lastModifiedAt": "2025-10-25T14:30:45.123Z",
      "key": "distribution-channel-us",
      "roles": ["ProductDistribution", "InventorySupply"],
      "name": {
        "en-US": "US Distribution Channel",
        "de-DE": "US-Vertriebskanal",
        "fr-FR": "Canal de distribution américain",
        "es-ES": "Canal de distribución de EE. UU."
      },
      "description": {
        "en-US": "Primary distribution channel for United States market",
        "de-DE": "Primärer Vertriebskanal für den US-Markt",
        "fr-FR": "Canal de distribution principal pour le marché américain",
        "es-ES": "Canal de distribución principal para el mercado estadounidense"
      },
      "address": {
        "id": "address-1",
        "key": "us-warehouse-address",
        "country": "US",
        "firstName": "John",
        "lastName": "Smith",
        "streetName": "Commerce Street",
        "streetNumber": "123",
        "postalCode": "94105",
        "city": "San Francisco",
        "state": "California",
        "phone": "+14155551234",
        "email": "warehouse@example.com"
      },
      "geoLocation": {
        "type": "Point",
        "coordinates": [-122.4194, 37.7749]
      }
    },
    {
      "id": "8c7e0b2a-45f3-4d8e-9a1b-c2f4e6d8a9b0",
      "version": 2,
      "createdAt": "2025-10-20T09:15:30.456Z",
      "lastModifiedAt": "2025-10-28T11:20:45.789Z",
      "key": "distribution-channel-eu",
      "roles": ["ProductDistribution"],
      "name": {
        "en-US": "EU Distribution Channel",
        "de-DE": "EU-Vertriebskanal",
        "fr-FR": "Canal de distribution européen",
        "es-ES": "Canal de distribución de la UE"
      },
      "description": {
        "en-US": "Main distribution channel for European market",
        "de-DE": "Hauptvertriebskanal für den europäischen Markt",
        "fr-FR": "Canal de distribution principal pour le marché européen",
        "es-ES": "Canal de distribución principal para el mercado europeo"
      },
      "address": {
        "id": "address-2",
        "key": "eu-warehouse-address",
        "country": "DE",
        "firstName": "Anna",
        "lastName": "Müller",
        "streetName": "Hauptstraße",
        "streetNumber": "45",
        "postalCode": "10115",
        "city": "Berlin",
        "phone": "+493012345678",
        "email": "warehouse-eu@example.com"
      }
    }
  ]
}

Check if Channel exists

Check if Channel exists by ID

HEAD

https://api.{region}.commercetools.com/{projectKey}/channels/{id}

Checks if a Channel exists with the provided id. Returns a 200 status if the Channel exists, or a 404 status otherwise.

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.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/channels/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Channel exists by Key

HEAD

https://api.{region}.commercetools.com/{projectKey}/channels/key={key}

Checks if a Channel exists with the provided key. Returns a 200 status if the Channel exists, or a 404 status otherwise.

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the Channel.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/channels/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Channel exists by Query Predicate

HEAD

https://api.{region}.commercetools.com/{projectKey}/channels

Checks if one or more Channels exist for the provided query predicate. Returns a 200 status if any Channels match the query predicate, or a 404 status otherwise.

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

QueryPredicate

Query Predicates on Channels are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.

Response:

200

Request Example:cURL

curl --head 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

Expansion

The parameter can be passed multiple times.

Request Body:ChannelDraftasapplication/json

Response:

201

Channel

application/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/channels -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "key" : "distribution-channel-us",
  "roles" : [ "ProductDistribution", "InventorySupply" ],
  "name" : {
    "en-US" : "US Distribution Channel",
    "de-DE" : "US-Vertriebskanal",
    "fr-FR" : "Canal de distribution américain",
    "es-ES" : "Canal de distribución de EE. UU."
  },
  "description" : {
    "en-US" : "Primary distribution channel for United States market",
    "de-DE" : "Primärer Vertriebskanal für den US-Markt",
    "fr-FR" : "Canal de distribution principal pour le marché américain",
    "es-ES" : "Canal de distribución principal para el mercado estadounidense"
  },
  "address" : {
    "key" : "us-warehouse-address",
    "country" : "US",
    "firstName" : "John",
    "lastName" : "Smith",
    "streetName" : "Commerce Street",
    "streetNumber" : "123",
    "postalCode" : "94105",
    "city" : "San Francisco",
    "state" : "California",
    "phone" : "+14155551234",
    "email" : "warehouse@example.com"
  },
  "geoLocation" : {
    "type" : "Point",
    "coordinates" : [ -122.4194, 37.7749 ]
  }
}
DATA

201 Response Example: Channeljson

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "createdAt": "2025-10-25T14:30:45.123Z",
  "lastModifiedAt": "2025-10-25T14:30:45.123Z",
  "key": "distribution-channel-us",
  "roles": ["ProductDistribution", "InventorySupply"],
  "name": {
    "en-US": "US Distribution Channel",
    "de-DE": "US-Vertriebskanal",
    "fr-FR": "Canal de distribution américain",
    "es-ES": "Canal de distribución de EE. UU."
  },
  "description": {
    "en-US": "Primary distribution channel for United States market",
    "de-DE": "Primärer Vertriebskanal für den US-Markt",
    "fr-FR": "Canal de distribution principal pour le marché américain",
    "es-ES": "Canal de distribución principal para el mercado estadounidense"
  },
  "address": {
    "id": "address-1",
    "key": "us-warehouse-address",
    "country": "US",
    "firstName": "John",
    "lastName": "Smith",
    "streetName": "Commerce Street",
    "streetNumber": "123",
    "postalCode": "94105",
    "city": "San Francisco",
    "state": "California",
    "phone": "+14155551234",
    "email": "warehouse@example.com"
  },
  "geoLocation": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  }
}

Update Channel

Update Channel by ID

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

Expansion

The parameter can be passed multiple times.

Request Body:

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.

Response:

200

Channel

application/json

Request Example:cURL

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-US" : "Updated US Distribution Channel",
      "de-DE" : "Aktualisierter US-Vertriebskanal",
      "fr-FR" : "Canal de distribution américain mis à jour",
      "es-ES" : "Canal de distribución de EE. UU. actualizado"
    }
  } ]
}
DATA

200 Response Example: Channeljson

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 2,
  "createdAt": "2025-10-25T14:30:45.123Z",
  "lastModifiedAt": "2025-11-05T16:45:22.456Z",
  "key": "distribution-channel-us",
  "roles": ["ProductDistribution", "InventorySupply"],
  "name": {
    "en-US": "Updated US Distribution Channel",
    "de-DE": "Aktualisierter US-Vertriebskanal",
    "fr-FR": "Canal de distribution américain mis à jour",
    "es-ES": "Canal de distribución de EE. UU. actualizado"
  },
  "description": {
    "en-US": "Primary distribution channel for United States market",
    "de-DE": "Primärer Vertriebskanal für den US-Markt",
    "fr-FR": "Canal de distribution principal pour le marché américain",
    "es-ES": "Canal de distribución principal para el mercado estadounidense"
  },
  "address": {
    "id": "address-1",
    "key": "us-warehouse-address",
    "country": "US",
    "firstName": "John",
    "lastName": "Smith",
    "streetName": "Commerce Street",
    "streetNumber": "123",
    "postalCode": "94105",
    "city": "San Francisco",
    "state": "California",
    "phone": "+14155551234",
    "email": "warehouse@example.com"
  },
  "geoLocation": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  }
}

Update Channel by Key

POST

https://api.{region}.commercetools.com/{projectKey}/channels/key={key}

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the Channel.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:

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.

Response:

200

Channel

application/json

Request Example:cURL

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-US" : "Updated US Distribution Channel",
      "de-DE" : "Aktualisierter US-Vertriebskanal",
      "fr-FR" : "Canal de distribution américain mis à jour",
      "es-ES" : "Canal de distribución de EE. UU. actualizado"
    }
  } ]
}
DATA

200 Response Example: Channeljson

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 2,
  "createdAt": "2025-10-25T14:30:45.123Z",
  "lastModifiedAt": "2025-11-05T16:45:22.456Z",
  "key": "distribution-channel-us",
  "roles": ["ProductDistribution", "InventorySupply"],
  "name": {
    "en-US": "Updated US Distribution Channel",
    "de-DE": "Aktualisierter US-Vertriebskanal",
    "fr-FR": "Canal de distribution américain mis à jour",
    "es-ES": "Canal de distribución de EE. UU. actualizado"
  },
  "description": {
    "en-US": "Primary distribution channel for United States market",
    "de-DE": "Primärer Vertriebskanal für den US-Markt",
    "fr-FR": "Canal de distribution principal pour le marché américain",
    "es-ES": "Canal de distribución principal para el mercado estadounidense"
  },
  "address": {
    "id": "address-1",
    "key": "us-warehouse-address",
    "country": "US",
    "firstName": "John",
    "lastName": "Smith",
    "streetName": "Commerce Street",
    "streetNumber": "123",
    "postalCode": "94105",
    "city": "San Francisco",
    "state": "California",
    "phone": "+14155551234",
    "email": "warehouse@example.com"
  },
  "geoLocation": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  }
}

Update actions

Set Custom Type in Address

Set CustomField in Address

Set GeoLocation

Change Key

`action` String	`"changeKey"`
`key` String	New value to set. Must not be empty.

Example: json

{
  "action": "changeKey",
  "key": "my-updated-key"
}

Change Name

`action` String	`"changeName"`
`name` LocalizedString	New value to set. Must not be empty.

Example: json

{
  "action": "changeName",
  "name": {
    "en-US": "Updated Channel Name",
    "de-DE": "Aktualisierter Kanalname",
    "fr-FR": "Nom de canal mis à jour",
    "es-ES": "Nombre de canal actualizado"
  }
}

Change Description

`action` String	`"changeDescription"`
`description` LocalizedString	New value to set. Must not be empty.

Example: json

{
  "action": "changeDescription",
  "description": {
    "en-US": "Updated channel description",
    "de-DE": "Aktualisierte Kanalbeschreibung",
    "fr-FR": "Description du canal mise à jour",
    "es-ES": "Descripción del canal actualizada"
  }
}

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": [
    "OrderExport",
    "OrderImport"
  ]
}

Add Roles

`action` String	`"addRoles"`
`roles` Array of ChannelRoleEnum	Value to append to the array.

Example: json

{
  "action": "addRoles",
  "roles": [
    "OrderExport"
  ]
}

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` BaseAddress	Value to set. If empty, any existing value will be removed.

Example: json

{
  "action": "setAddress",
  "address": {
    "key": "warehouse-address-key",
    "country": "US",
    "firstName": "John",
    "lastName": "Doe",
    "streetName": "Market Street",
    "streetNumber": "456",
    "postalCode": "94103",
    "city": "San Francisco",
    "state": "California",
    "phone": "+14155559876",
    "email": "johndoe@example.com"
  }
}

Set Custom Type

`action` String	`"setCustomType"`
`type` TypeResourceIdentifier	Defines the Type that extends the Channel with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Channel.
`fields` FieldContainer	Sets the Custom Fields fields for the Channel.

Example: json

{
  "action": "setCustomType",
  "type": {
    "key": "channel-custom-type",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set CustomField

`action` String	`"setCustomField"`
`name` String	Name of the Custom Field.
`value` CustomFieldValue	If `value` is absent or `null`, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If `value` is provided, it is set for the field defined by `name`.

Example: json

{
  "action": "setCustomField",
  "name": "exampleStringField",
  "value": "TextString"
}

Set Custom Type in Address

`action` String	`"setAddressCustomType"`
`type` TypeResourceIdentifier	Defines the Type that extends the `address` with Custom Fields. If absent, any existing Type and Custom Fields are removed from the `address`.
`fields` FieldContainer	Sets the Custom Fields fields for the `address`.

Example: json

{
  "action": "setAddressCustomType",
  "type": {
    "key": "address-custom-type",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set CustomField in Address

`action` String	`"setAddressCustomField"`
`name` String	Name of the Custom Field.
`value` CustomFieldValue	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. Removing a field that does not exist returns an InvalidOperation error.

Example: json

{
  "action": "setAddressCustomField",
  "name": "exampleStringField",
  "value": "TextString"
}

Set GeoLocation

`action` String	`"setGeoLocation"`
`geoLocation` GeoJson	Value to set.

Example: json

{
  "action": "setGeoLocation",
  "geoLocation": {
    "type": "Point",
    "coordinates": [
      -122.4084,
      37.7849
    ]
  }
}

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

DELETE

https://api.{region}.commercetools.com/{projectKey}/channels/{id}

Returns a ReferenceExists error if other resources reference the Channel to be deleted.

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:

`version` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.

Response:

200

Channel

application/json

Request Example:cURL

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

200 Response Example: Channeljson

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "createdAt": "2025-10-25T14:30:45.123Z",
  "lastModifiedAt": "2025-10-25T14:30:45.123Z",
  "key": "distribution-channel-us",
  "roles": ["ProductDistribution", "InventorySupply"],
  "name": {
    "en-US": "US Distribution Channel",
    "de-DE": "US-Vertriebskanal",
    "fr-FR": "Canal de distribution américain",
    "es-ES": "Canal de distribución de EE. UU."
  },
  "description": {
    "en-US": "Primary distribution channel for United States market",
    "de-DE": "Primärer Vertriebskanal für den US-Markt",
    "fr-FR": "Canal de distribution principal pour le marché américain",
    "es-ES": "Canal de distribución principal para el mercado estadounidense"
  },
  "address": {
    "id": "address-1",
    "key": "us-warehouse-address",
    "country": "US",
    "firstName": "John",
    "lastName": "Smith",
    "streetName": "Commerce Street",
    "streetNumber": "123",
    "postalCode": "94105",
    "city": "San Francisco",
    "state": "California",
    "phone": "+14155551234",
    "email": "warehouse@example.com"
  },
  "geoLocation": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  }
}

Delete Channel by Key

DELETE

https://api.{region}.commercetools.com/{projectKey}/channels/key={key}

Returns a ReferenceExists error if other resources reference the Channel to be deleted.

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the Channel.

Query parameters:

`version` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.

Response:

200

Channel

application/json

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/channels/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: Channeljson

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "version": 1,
  "createdAt": "2025-10-25T14:30:45.123Z",
  "lastModifiedAt": "2025-10-25T14:30:45.123Z",
  "key": "distribution-channel-us",
  "roles": ["ProductDistribution", "InventorySupply"],
  "name": {
    "en-US": "US Distribution Channel",
    "de-DE": "US-Vertriebskanal",
    "fr-FR": "Canal de distribution américain",
    "es-ES": "Canal de distribución de EE. UU."
  },
  "description": {
    "en-US": "Primary distribution channel for United States market",
    "de-DE": "Primärer Vertriebskanal für den US-Markt",
    "fr-FR": "Canal de distribution principal pour le marché américain",
    "es-ES": "Canal de distribución principal para el mercado estadounidense"
  },
  "address": {
    "id": "address-1",
    "key": "us-warehouse-address",
    "country": "US",
    "firstName": "John",
    "lastName": "Smith",
    "streetName": "Commerce Street",
    "streetNumber": "123",
    "postalCode": "94105",
    "city": "San Francisco",
    "state": "California",
    "phone": "+14155551234",
    "email": "warehouse@example.com"
  },
  "geoLocation": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  }
}

Channels

Representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Channel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ChannelDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ChannelPagedQueryResponse.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ChannelReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ChannelKeyReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ChannelResourceIdentifier.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ChannelRoleEnum.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get Channel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get Channel by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get Channel by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Query Channels.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if Channel exists.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if Channel exists by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if Channel exists by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if Channel exists by Query Predicate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create Channel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update Channel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update Channel by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update Channel by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update actions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Change Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Change Name.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Change Description.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set Roles.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Add Roles.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Remove Roles.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set Address.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set Custom Type.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set CustomField.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set Custom Type in Address.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set CustomField in Address.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set GeoLocation.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Delete Channel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Delete Channel by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Delete Channel by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Representations

Channel

ChannelDraft

ChannelPagedQueryResponse

ChannelReference

ChannelKeyReference

ChannelResourceIdentifier

ChannelRoleEnum

Get Channel

Get Channel by ID

Get Channel by Key

Query Channels

Check if Channel exists

Check if Channel exists by ID

Check if Channel exists by Key

Check if Channel exists by Query Predicate

Create Channel

Update Channel

Update Channel by ID

Update Channel by Key

Update actions

Change Key

Change Name

Change Description

Set Roles

Add Roles

Remove Roles

Set Address

Set Custom Type

Set CustomField

Set Custom Type in Address

Set CustomField in Address

Set GeoLocation

Delete Channel

Delete Channel by ID

Delete Channel by Key