Channels

B2CB2BB2XPRODUCT CATALOGAgenticLift

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

Get Channel

Get Channel by ID

GET
https://api.{region}.commercetools.com/{projectKey}/channels/{id}
OAuth 2.0 Scopes:
view_channels:{projectKey}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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

Channel

as
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_channels:{projectKey}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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

Channel

as
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_channels:{projectKey}view_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
The parameter can be passed multiple times.
sort
​
String
​

Use to sort query results.

For more information, see Sorting.
The parameter can be passed multiple times.
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
limit
​
Int32
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int32
​
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

as
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_channels:{projectKey}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_channels:{projectKey}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_channels:{projectKey}view_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
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_channels:{projectKey}manage_products:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Request Body:ChannelDraftasapplication/json
Response:
201

Channel

as
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_channels:{projectKey}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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int64​
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

as
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_channels:{projectKey}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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int64​
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

as
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

Change Key

action​
String​
"changeKey"
key​
String​

New value to set.

If set to an empty value, an InvalidOperation error is returned.
If the value is used by another Channel in the Project, a DuplicateField error is returned.
Example: json
{
  "action": "changeKey",
  "key": "my-updated-key"
}

Change Name

action​
String​
"changeName"
name​
LocalizedString​

New value to set.

If set to an empty value, an InvalidOperation error is returned.
If the new value is the same as the current value, an InvalidOperation error is returned.
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.

If set to an empty value, an InvalidOperation error is returned.
If the new value is the same as the current value, an InvalidOperation error is returned.
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 set to an empty array, an InvalidOperation error is returned.
If the new value is the same as the current value, an InvalidOperation error is returned.
Default: InventorySupply​
Example: json
{
  "action": "setRoles",
  "roles": [
    "OrderExport",
    "OrderImport"
  ]
}

Add Roles

action​
String​
"addRoles"
roles​
Array of ChannelRoleEnum​

Value to append to the array.

If the specified roles are already present, an InvalidOperation error is returned.
Example: json
{
  "action": "addRoles",
  "roles": [
    "OrderExport"
  ]
}

Remove Roles

action​
String​
"removeRoles"
roles​
Array of ChannelRoleEnum​

Value to remove from the array.

If none of the specified roles are already present, an InvalidOperation error is returned.
If all roles from the Channel are removed, an InvalidOperation error is returned.
Example: json
{
  "action": "removeRoles",
  "roles": [
    "InventorySupply"
  ]
}

Set Address

action​
String​
"setAddress"
address​
BaseAddress​

Value to set. If omitted, any existing value is 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​
Object containing the Custom Fields fields for the Channel.
Required if at least one Custom Field is defined as required in the fieldDefinitions of the referenced Type.
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

To set a Custom Type for a Channel, Channel.address must be set; otherwise, an InvalidInput error is returned.
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​
Object containing the Custom Fields fields for the address.
Required if at least one Custom Field is defined as required in the fieldDefinitions of the referenced Type.
Example: json
{
  "action": "setAddressCustomType",
  "type": {
    "key": "address-custom-type",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set CustomField in Address

To set a Custom Field for a Channel, Channel.address must be set; otherwise, an InvalidInput error is returned.
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.
To avoid dependency conflicts and errors, delete resources that reference the Channel in the correct order before deleting the Channel itself. You must delete all active and anonymous Carts that reference the Channel first, then delete the Orders that reference the Channel, and finally delete the Stores that reference the Channel before you can safely delete the Channel itself.

Delete Channel by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/channels/{id}
If the Channel is referenced by a resource, a ReferenceExists error is returned.
OAuth 2.0 Scopes:
manage_channels:{projectKey}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
​
Int64
​

Last seen version of the resource.

expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

Channel

as
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}
If the Channel is referenced by a resource, a ReferenceExists error is returned.
OAuth 2.0 Scopes:
manage_channels:{projectKey}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
​
Int64
​

Last seen version of the resource.

expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

Channel

as
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]
  }
}

Representations

Channel

id​
String​

Unique identifier of the Channel.

version​
Int64​

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.

If set to an empty value, an InvalidOperation error is returned.
If the value is used by another Channel in the Project, a DuplicateField error is returned.
roles​
Array of ChannelRoleEnum​

Roles of the Channel.

The Channel must have at least one role. If set to an empty array, an InvalidOperation error is returned.
Default: InventorySupply​
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​
Int64​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int64​
Number of elements skipped.
Default: 0​Maximum: 10000​
count​
Int64​

Actual number of results returned.

total​
Int64​
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
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

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
Example: json
{
  "typeId": "channel",
  "key": "distribution-channel-us"
}

ChannelRoleEnum

Describes how a Channel is used. 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 identifies a synchronization destination used when storing export information in SyncInfo. You can reference it with Update SyncInfo on Orders and Order Edits.
OrderImport
Channel identifies a synchronization destination used when storing import information in SyncInfo. You can reference it with Update SyncInfo on Orders and Order Edits.
Primary
Marks the Channel as the default or preferred Channel among Channels with the same role. It can be combined with another role, for example InventorySupply.