---
canonical: https://amplience.com/developers/docs/workforce/flows/action-reference/commerce-actions/commercetools-actions/
title: Commercetools actions
description: Explore the Commercetools extension actions for Workforce flows, enabling you to retrieve products, categories, and customer groups from Commercetools as part of automated content processes.
audience: Business User
date_published: 2026-04-13
date_modified: 2026-05-19
---

# commercetools actions

The commercetools extension provides actions for retrieving product, category, and customer group data from commercetools within Workforce Flows. Use these actions to fetch individual records or search and browse content as part of your automated content processes.

The commercetools action extension can be installed from the [Workforce integration marketplace](https://amplience.com/developers/docs/workforce/setup/integrations/).

See [commercetools configuration](https://amplience.com/developers/docs/workforce/setup/integrations/commercetools/) for details of how to obtain the credentials you need to configure the commercetools action extension.

> **Tip:** These action descriptions cover the most commonly used inputs and outputs. When designing flows, you may also notice additional input and output variables.

## Shared price selection inputs

Several actions support the following optional price selection inputs. These can only be used in conjunction with the **Price Currency** parameter.

| Input | Type | Description |
|---|---|---|
| `priceCurrency` | string | Currency code in ISO 4217 format (e.g. `USD`) |
| `priceCountry` | string | Country code in ISO 3166 format (e.g. `US`) |
| `priceCustomerGroup` | string | ID of an existing Customer Group for price selection |
| `priceCustomerGroupAssignments` | string | Comma-separated IDs of Customer Groups for price selection when using multiple groups |
| `priceChannel` | string | ID of an existing Channel for price selection |
| `priceRecurrencePolicy` | string | ID of an existing RecurrencePolicy for price selection |

## Get product by ID

Retrieves full product data for a single product by its ID from Commercetools.

**Inputs**

| Input | Type | Required | Description |
|---|---|---:|---|
| `id` | string | Yes | The unique identifier of the product |
| `locale` | string | No | Locale identifier (e.g. `fr`) that determines the localized product data returned |
| `expand` | string | No | Comma-separated list of related resources to expand in the response |
| `priceCurrency` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceCountry` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceCustomerGroup` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceCustomerGroupAssignments` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceChannel` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceRecurrencePolicy` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |

**Outputs**

| Output | Type | Description |
|---|---|---|
| `product` | object | The full product object. See [product object](#product-object) below |

## Update product by ID

Updates a product by its ID in Commercetools using one or more update actions.

**Inputs**

| Input | Type | Required | Description |
|---|---|---:|---|
| `id` | string | Yes | The unique identifier of the product to update |
| `version` | string | Yes | The expected version of the product. If it does not match the actual version, a `ConcurrentModification` error is returned |
| `actions` | array | Yes | An array of update action objects to perform on the product. See [update actions](#product-update-actions) below |

#### Product update actions

Each entry in the `actions` array must include the following fields:

| Field | Type | Required | Description |
|---|---|---:|---|
| `action` | string | Yes | The name of the update action to perform. Accepted values: `changeName`, `setDescription`, `setSearchKeywords`, `setMetaTitle`, `setMetaDescription`, `setMetaKeywords` |
| `payload` | string | Yes | A JSON-stringified object containing the action data. The structure depends on the action type (e.g. `{"name": {"en": "New product name"}}` for `changeName`). See the [Commercetools update actions documentation](https://docs.commercetools.com/api/projects/products#update-actions) |

**Outputs**

| Output | Type | Description |
|---|---|---|
| `product` | object | The updated product object. See [product object](#product-object) below |

## Get basic product by ID

Retrieves a simplified set of product data for a single product by its ID from Commercetools. Intended for use with commerce repositories.

**Inputs**

| Input | Type | Required | Description |
|---|---|---:|---|
| `id` | string | Yes | The unique identifier of the product |
| `locale` | string | No | Locale identifier (e.g. `fr`) that determines the localized product data returned |
| `expand` | string | No | Comma-separated list of related resources to expand in the response |
| `priceCurrency` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceCountry` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceCustomerGroup` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceCustomerGroupAssignments` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceChannel` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceRecurrencePolicy` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |

**Outputs**

| Output | Type | Description |
|---|---|---|
| `product.id` | string | Product ID |
| `product.name` | string | Product name |
| `product.description` | string | Product description |
| `product.images` | array | List of image objects, each with a `url` field |

## Get products by search term

Retrieves a paginated list of products matching a search term from Commercetools. Full-text search is performed on localized product content in the specified language.

**Inputs**

| Input | Type | Required | Description |
|---|---|---:|---|
| `term` | string | Yes | The text to search for. Full-text search is performed in the localized product content of the specified language |
| `locale` | string | No | Locale identifier (e.g. `fr`) that determines the localized product data returned |
| `markMatchingVariants` | string | No | Set to `true` to mark matching variants in the search result |
| `fuzzy` | string | No | Set to `true` to apply fuzzy search on the search term |
| `fuzzyLevel` | string | No | Overrides the default fuzzy level. Only applicable when `fuzzy` is `true`. Accepted values: `0` (1-2 character terms), `1` (3-5 character terms), `2` (more than 5 characters) |
| `expand` | string | No | Comma-separated list of related resources to expand in the response |
| `staged` | string | No | Whether to search in current or staged product projections. Setting to `true` requires the `view_products` OAuth scope |
| `localeProjection` | string | No | Comma-separated list of locales for locale-based projection |
| `storeProjection` | string | No | Key of an existing Store. The store's languages, countries, distribution channels, and supply channels are used for projections based on locale, price, and inventory |
| `priceCurrency` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceCountry` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceCustomerGroup` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceCustomerGroupAssignments` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceChannel` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceRecurrencePolicy` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `pagination.offset` | string | No | Starting index for paginated results. Default: `0` |
| `pagination.limit` | string | No | Maximum number of results. Default: `20`. Values above `20` are ignored |
| `pagination.sort` | string | No | Comma-separated list of fields to sort by |

**Outputs**

| Output | Type | Description |
|---|---|---|
| `total` | number | Total number of matching products |
| `start` | number | Start index of the current page |
| `end` | number | End index of the current page |
| `products` | array | List of product projection objects. See [product projection object](#product-projection-object) below |

## Get basic products by optional keyword

Retrieves a cursor-paginated list of products matching an optional keyword from Commercetools. Intended for use with commerce repositories.

**Inputs**

| Input | Type | Required | Description |
|---|---|---:|---|
| `keyword` | string | No | The text to search for. If omitted, returns all products |
| `before` | string | No | A pagination cursor to retrieve the page of products before a given position. Use the `startCursor` value from a previous response |
| `after` | string | No | A pagination cursor to retrieve the page of products after a given position. Use the `endCursor` value from a previous response |

**Outputs**

| Output | Type | Description |
|---|---|---|
| `pageInfo.startCursor` | string | Cursor for the first item in the current page |
| `pageInfo.endCursor` | string | Cursor for the last item in the current page |
| `pageInfo.hasPreviousPage` | boolean | Whether a previous page exists |
| `pageInfo.hasNextPage` | boolean | Whether a next page exists |
| `products` | array | List of basic product objects, each with `id`, `name`, `description`, and `images` (array of objects with a `url` field) |

## Get products by category ID

Retrieves a paginated list of products belonging to a category from Commercetools.

**Inputs**

| Input | Type | Required | Description |
|---|---|---:|---|
| `id` | string | Yes | The unique identifier of the category |
| `locale` | string | No | Locale identifier (e.g. `fr`) that determines the localized product data returned |
| `markMatchingVariants` | string | No | Set to `true` to mark matching variants in the search result |
| `expand` | string | No | Comma-separated list of related resources to expand in the response |
| `staged` | string | No | Whether to search in current or staged product projections. Setting to `true` requires the `view_products` OAuth scope |
| `localeProjection` | string | No | Comma-separated list of locales for locale-based projection |
| `storeProjection` | string | No | Key of an existing Store used for projections based on locale, price, and inventory |
| `priceCurrency` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceCountry` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceCustomerGroup` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceCustomerGroupAssignments` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceChannel` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `priceRecurrencePolicy` | string | No | See [shared price selection inputs](#shared-price-selection-inputs) |
| `pagination.offset` | string | No | Starting index for paginated results. Default: `0` |
| `pagination.limit` | string | No | Maximum number of results. Default: `20`. Values above `20` are ignored |
| `pagination.sort` | string | No | Comma-separated list of fields to sort by |

**Outputs**

| Output | Type | Description |
|---|---|---|
| `total` | number | Total number of matching products |
| `start` | number | Start index of the current page |
| `end` | number | End index of the current page |
| `products` | array | List of product projection objects. See [product projection object](#product-projection-object) below |

## Get category by ID

Retrieves a single category by its ID from Commercetools.

**Inputs**

| Input | Type | Required | Description |
|---|---|---:|---|
| `id` | string | Yes | The unique identifier of the category |
| `locale` | string | No | Locale identifier (e.g. `fr`) that determines the localized category data returned |
| `expand` | string | No | Comma-separated list of related resources to expand in the response |

**Outputs**

| Output | Type | Description |
|---|---|---|
| `category` | object | The category object. See [category object](#category-object) below |

## Update category by ID

Updates a category by its ID in Commercetools using one or more update actions.

**Inputs**

| Input | Type | Required | Description |
|---|---|---:|---|
| `id` | string | Yes | The unique identifier of the category to update |
| `version` | string | Yes | The expected version of the category. If it does not match the actual version, a `ConcurrentModification` error is returned |
| `actions` | array | Yes | An array of update action objects to perform on the category. See [update actions](#category-update-actions) below |

#### Category update actions

Each entry in the `actions` array must include the following fields:

| Field | Type | Required | Description |
|---|---|---:|---|
| `action` | string | Yes | The name of the update action to perform. Accepted values: `changeName`, `changeSlug`, `setDescription`, `setMetaTitle`, `setMetaDescription`, `setMetaKeywords` |
| `payload` | string | Yes | A JSON-stringified object containing the action data. The structure depends on the action type (e.g. `{"name": {"en": "New category name"}}` for `changeName`). See the [Commercetools update actions documentation](https://docs.commercetools.com/api/projects/categories#update-actions) |

**Outputs**

| Output | Type | Description |
|---|---|---|
| `category` | object | The updated category object. See [category object](#category-object) below |

## Get categories by search term

Retrieves a paginated list of categories matching a search term from Commercetools. Full-text search is performed on localized category content in the specified language.

**Inputs**

| Input | Type | Required | Description |
|---|---|---:|---|
| `term` | string | Yes | The text to search for. Full-text search is performed in the localized category content of the specified language |
| `locale` | string | No | Locale identifier (e.g. `fr`) that determines the localized category data returned |
| `expand` | string | No | Comma-separated list of related resources to expand in the response |
| `pagination.offset` | string | No | Starting index for paginated results. Default: `0` |
| `pagination.limit` | string | No | Maximum number of results. Default: `20`. Values above `20` are ignored |
| `pagination.sort` | string | No | Comma-separated list of fields to sort by |

**Outputs**

| Output | Type | Description |
|---|---|---|
| `total` | number | Total number of matching categories |
| `start` | number | Start index of the current page |
| `end` | number | End index of the current page |
| `categories` | array | List of category objects. See [category object](#category-object) below |

## Get customer group by ID

Retrieves a single customer group by its ID from Commercetools.

**Inputs**

| Input | Type | Required | Description |
|---|---|---:|---|
| `id` | string | Yes | The unique identifier of the customer group |
| `expand` | string | No | Comma-separated list of related resources to expand in the response |

**Outputs**

| Output | Type | Description |
|---|---|---|
| `customerGroup.id` | string | Customer group ID |
| `customerGroup.version` | number | Version |
| `customerGroup.createdAt` | string | Created date |
| `customerGroup.lastModifiedAt` | string | Last modified date |
| `customerGroup.createdBy` | object | Creator details (clientId, isPlatformClient, anonymousId, customer, user) |
| `customerGroup.lastModifiedBy` | object | Last modifier details (clientId, isPlatformClient, anonymousId, customer, user) |
| `customerGroup.name` | string | Customer group name |
| `customerGroup.key` | string | Customer group key |

## Get customer groups

Retrieves all customer groups from Commercetools.

**Inputs**

| Input | Type | Required | Description |
|---|---|---:|---|
| `pagination.offset` | string | No | Starting index for paginated results. Default: `0` |
| `pagination.limit` | string | No | Maximum number of results. Default: `20`. Values above `20` are ignored |

**Outputs**

| Output | Type | Description |
|---|---|---|
| `total` | number | Total number of customer groups |
| `start` | number | Start index of the current page |
| `end` | number | End index of the current page |
| `customerGroups` | array | List of customer group objects |

## Product object

The full product object returned by [Get product by ID](#get-product-by-id) and [Update product by ID](#update-product-by-id) contains the following fields:

| Field | Type | Description |
|---|---|---|
| `id` | string | Product ID |
| `version` | number | Version |
| `lastModifiedAt` | string | Last modified date |
| `createdBy` | object | Creator details (clientId, isPlatformClient, anonymousId, customer, user) |
| `lastModifiedBy` | object | Last modifier details (clientId, isPlatformClient, anonymousId, customer, user) |
| `productType` | object | Product type reference (typeId, id) |
| `masterData.published` | boolean | Whether the product is published |
| `masterData.hasStagedChanges` | boolean | Whether there are staged (unpublished) changes |
| `masterData.current` | object | The current published product data. See [product data fields](#product-data-fields) |
| `masterData.staged` | object | The staged (unpublished) product data. See [product data fields](#product-data-fields) |

### Product data fields

Both `masterData.current` and `masterData.staged` share the following structure:

| Field | Type | Description |
|---|---|---|
| `name` | object | Localized product name (map of locale to string) |
| `slug` | object | Localized URL slug (map of locale to string) |
| `metaTitle` | object | Localized meta title (map of locale to string) |
| `metaDescription` | object | Localized meta description (map of locale to string) |
| `localized.name` | string | Product name resolved to the requested locale |
| `localized.description` | string | Product description resolved to the requested locale |
| `localized.slug` | string | URL slug resolved to the requested locale |
| `localized.metaTitle` | string | Meta title resolved to the requested locale |
| `localized.metaDescription` | string | Meta description resolved to the requested locale |
| `masterVariant` | object | The master variant (id, images) |
| `variants` | array | Additional variants, each with id and images |

Each variant's `images` array contains objects with `url` and `dimensions` (object with `w` and `h`).

## Product projection object

The product projection objects returned by search and category listing actions contain the following fields:

| Field | Type | Description |
|---|---|---|
| `id` | string | Product ID |
| `version` | string | Version |
| `productType` | object | Product type reference (typeId, id) |
| `name` | object | Localized product name (map of locale to string) |
| `description` | object | Localized product description (map of locale to string) |
| `slug` | object | Localized URL slug (map of locale to string) |
| `metaTitle` | object | Localized meta title (map of locale to string) |
| `metaDescription` | object | Localized meta description (map of locale to string) |
| `localized.name` | string | Product name resolved to the requested locale |
| `localized.description` | string | Product description resolved to the requested locale |
| `localized.slug` | string | URL slug resolved to the requested locale |
| `localized.metaTitle` | string | Meta title resolved to the requested locale |
| `localized.metaDescription` | string | Meta description resolved to the requested locale |
| `masterVariant` | object | The master variant (id, images) |
| `variants` | array | Additional variants, each with id and images |
| `hasStagedChanges` | boolean | Whether there are staged changes |
| `published` | boolean | Whether the product is published |
| `key` | string | Product key |
| `priceMode` | string | Price mode |
| `createdAt` | string | Created date |
| `lastModifiedAt` | string | Last modified date |

Each variant's `images` array contains objects with `url` and `dimensions` (object with `w` and `h`).

## Category object

The category object returned by [Get category by ID](#get-category-by-id), [Update category by ID](#update-category-by-id), and [Get categories by search term](#get-categories-by-search-term) contains the following fields:

| Field | Type | Description |
|---|---|---|
| `id` | string | Category ID |
| `version` | number | Version |
| `versionModifiedAt` | string | Version modified date |
| `lastMessageSequenceNumber` | number | Last message sequence number |
| `createdAt` | string | Created date |
| `lastModifiedAt` | string | Last modified date |
| `createdBy` | object | Creator details (clientId, isPlatformClient, anonymousId, customer, user) |
| `lastModifiedBy` | object | Last modifier details (clientId, isPlatformClient, anonymousId, customer, user) |
| `key` | string | Category key |
| `orderHint` | string | Order hint for sorting |
| `externalId` | string | External identifier |
| `ancestors` | array | List of ancestor category references (typeId, id) |
| `parent` | object | Parent category reference (typeId, id) |
| `name` | object | Localized category name (map of locale to string) |
| `description` | object | Localized description (map of locale to string) |
| `slug` | object | Localized URL slug (map of locale to string) |
| `localized.name` | string | Category name resolved to the requested locale |
| `localized.description` | string | Category description resolved to the requested locale |
| `localized.slug` | string | URL slug resolved to the requested locale |

## Related pages

[Adding actions to flows](https://amplience.com/developers/docs/workforce/flows/action-reference/#adding-actions-to-flows)

[Inputs, outputs and ports](https://amplience.com/developers/docs/workforce/flows/action-reference/#inputs-outputs-and-ports)

[Input field variables](https://amplience.com/developers/docs/workforce/flows/action-reference/#input-field-variables)

[Developing extensions](https://amplience.com/developers/docs/workforce/flows/developing-extensions/)