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.

See commercetools configuration 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
priceCountry	string	No	See shared price selection inputs
priceCustomerGroup	string	No	See shared price selection inputs
priceCustomerGroupAssignments	string	No	See shared price selection inputs
priceChannel	string	No	See shared price selection inputs
priceRecurrencePolicy	string	No	See shared price selection inputs

Outputs

Output	Type	Description
product	object	The full product object. See 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 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

Outputs

Output	Type	Description
product	object	The updated product object. See 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
priceCountry	string	No	See shared price selection inputs
priceCustomerGroup	string	No	See shared price selection inputs
priceCustomerGroupAssignments	string	No	See shared price selection inputs
priceChannel	string	No	See shared price selection inputs
priceRecurrencePolicy	string	No	See 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
priceCountry	string	No	See shared price selection inputs
priceCustomerGroup	string	No	See shared price selection inputs
priceCustomerGroupAssignments	string	No	See shared price selection inputs
priceChannel	string	No	See shared price selection inputs
priceRecurrencePolicy	string	No	See 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 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
priceCountry	string	No	See shared price selection inputs
priceCustomerGroup	string	No	See shared price selection inputs
priceCustomerGroupAssignments	string	No	See shared price selection inputs
priceChannel	string	No	See shared price selection inputs
priceRecurrencePolicy	string	No	See 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 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 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 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

Outputs

Output	Type	Description
category	object	The updated category object. See 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 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 and 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
masterData.staged	object	The staged (unpublished) product data. See product data fields

Product data fields

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

Field	Type	Description
name	string	Localized product name
slug	string	Localized URL slug
metaTitle	string	Meta title
metaDescription	string	Meta description
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	string	Localized product name
description	string	Localized product description
slug	string	Localized URL slug
metaTitle	string	Meta title
metaDescription	string	Meta description
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, Update category by ID, and 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	string	Localized category name
slug	string	Localized URL slug

Related pages

Adding actions to flows

Inputs, outputs and ports

Input field variables

Developing extensions