More Products

commercetools extension setup and installation instructions

Last updated: Sep-26-2023

In order to set up and install the commercetools extension, you need to make sure you have your prerequisites in place, add structured metadata in Cloudinary, and install your preferred microservice.


Make sure you have a Cloudinary account. You can start by signing up for a Free plan. When your requirements grow, you can upgrade to a plan that best fits your needs.

Make sure that you have the following information readily available. When executing the deployment commands, e.g., sam deploy --guided, you’ll be asked for these configurations:

Parameter Example Description
CloudName abcdef123 Your Cloudinary cloud name.
CloudApiKey 123456789 Your Cloudinary API key.
CloudApiSecret ABCdef123 Your Cloudinary API secret.
PropertySku commercetools_sku The Cloudinary structured metadata field that contains the SKU of the Product it’s associated with.
PropertyPublish commercetools_publish The Cloudinary structured metadata field that triggers an action in your storefront when changed.
AuthUrl The commercetools Auth URL of your project.
ClientId The client ID of your commercetools project.
ApiUrl AbC-dEf-123 The commercetools API URL of your project.
ProjectKey abc_123 The commercetools project key.
CtApiSecret ABCdef123 The API secret for the provided commercetools API key.

Add metadata in Cloudinary

Create the following structured metadata fields in Cloudinary (see Adding structured metadata fields for instructions):

Required structured metadata fields

You can use any name you'd like for your structured metadata fields. However, you must use the text specified in the table as the field's external ID.

External ID Type Description
commercetools_sku Text Specifies the SKU of the Product that the Cloudinary asset is linked to.

Note: An asset without a value for this field isn't linked to a Product.

commercetools_publish Single-selection list (cld_ct_publish, cld_ct_draft, cld_ct_unpublish) Changing the value for this field triggers one of the following actions:

- cld_ct_publish: Adds the asset to the published ProductVariant.

- cld_ct_draft: Adds the asset to the ProductVariantDraft.

- cld_ct_unpublish: Removes the asset from the published ProductVariant.

Required structured metadata fields

Optional metadata fields

You can optionally create other fields in Cloudinary that will update commercetools Product Assets Attributes when you publish the asset. Just make sure the external ID of the field in Cloudinary matches the name of the Attribute used in commercetools.

Optional field for positioning assets on your PDP

You can control the position of the commercetools Product Asset on the PDP page via Cloudinary. Create a field in Cloudinary with a specific external_id, for example "sortNumber", and make sure you use the same name in your commercetools configuration for this parameter when deploying the website or app.

The commercetools Product Asset’s position on the PDP is updated according to the new value in the "sortNumber" field, at the time that the asset is published.

Sort structured metadata fields

Install a microservice

The serverless microservice that drives the integration of Cloudinary assets in your commercetools instance can be hosted on one of the following widely-used cloud providers: Amazon AWS, Google Cloud Platform, or Microsoft Azure.

Amazon AWS

The integration is built on top of AWS Cloudformation using the following services:

  • ECR to host the used Lambda docker image
  • API Gateway for the webhook entrypoint
  • AWS Lambda to process the notification
  • Secrets manager for API key management


  • AWS & SAM CLI installed
  • An account with permissions to create and manage AWS Resources
  • Docker CLI to build your Lambda container image


The GitHub repository includes an automated installation script to create the Secrets and a SAM template with:

  • API Gateway with SQS integration
  • AWS Lambda with an SQS trigger
  1. Create secret manager secrets, store the ARN of your secrets to be used later during deployment of your stack:

    Cloudinary API secret:

    commercetools API secret:

  2. Build SAM template:

  3. Deploy SAM template:

  4. The output returns your webhook URL. Enter that URL in the Notification URL field on the Upload page of the Console Settings.

Google Cloud Platform

The GCP integration uses the following resources:

  • API Gateway for the webhook entrypoint with an OpenAPI spec
  • Cloud Run to handle incoming notifications by posting it to a PUB/SUB
  • PUB/SUB topic for all incoming Cloudinary notifications
  • Subscription on the PUB/SUB to pass all messages to Cloud Run
  • Cloud Run to process the notifications asynchronously
    • Failed processes are moved to $Topic-dead-letter
  • Secrets to store API keys


The GitHub repository includes detailed installation steps and command line scripts to install the required resources.

Microsoft Azure

The Azure integration uses the following resources in a Bicep template:

  • Storage account
  • App service plan
  • App insights
  • Service Bus + Queue
  • Function
  • KeyVault
  • API management


The GitHub repository includes detailed installation steps and command line scripts to install the required resources.

The easiest way for you to set up the Azure integration is by using the provided Powershell script.

Start by editing the settings JSON file, found at /azure/settings/commercetools.json and fill in the following values:

  • Subscription: The name of the Azure Subscription where resources will be deployed.
  • ResourceGroup: The name of the Azure ResourceGroup where resources will be deployed.
  • KeyVaultName: The desired name for the KeyVault.
  • ApplicationId: The desired name for the application (resources will be named, for example, apim-<applicationId>, func-<applicationId>, etc.)

Once set up, open Powershell with the Azure CLI installed:

  • Go to /azure/scripts
  • Run .\deploy-initial.ps1

✔️ Feedback sent!

Rate this page: