Learn about the concepts and terminology of commercetools Connect.

What is commercetools Connect

commercetools Connect lets you add functionality to your Composable Commerce Project without needing to buy and maintain dedicated hosting or runtime environments.

commercetools Connect provides a runtime environment for running small applications, referred to as Connect applications. Connect applications can be developed by anyone, and they are deployed to Composable Commerce Projects using the Connect API.

Example use case for commercetools Connect

A Composable Commerce customer has hired a software development company to add the following functionality to their Composable Commerce Project:

  • Validating the contents of carts.
  • Sending order confirmation emails.
  • Running daily maintenance, updates, or syncs with external systems.
  • Extending the Merchant Center to manage the order confirmation emails.

To do this, the Composable Commerce customer and software development company would usually need to develop and maintain separate systems/hosting for this functionality.

Who is commercetools Connect for

commercetools Connect provides advantages to creators (application developers) and clients (Composable Commerce customers).

Creators can develop public or private applications using JavaScript/TypeScript or Java, and enjoy a simplified development and publishing process.

Clients can deploy applications without needing to manage hosting or runtime environments.

In the example use case, the software development company would be the creator and the Composable Commerce customer would be the client.

The commercetools Connect workflow

The following steps outline how creators and clients use commercetools Connect.

  1. Creators develop Connect applications and store them in a GitHub repository.

  2. Creators use the Connect API to create a ConnectorStaged that references this GitHub repository.

  3. Creators publish their ConnectorStaged. Once published, the ConnectorStaged creates/updates a Connector.

  4. Clients use the Connect API to create a Deployment that includes a reference to this Connector. The Connector is now deployed to the client's Composable Commerce Project.

In the example use case, the software development company would develop three Connect applications (one for each function), save their code to a GitHub repository, and use the Connect API to create and publish a ConnectorStaged.

The Composable Commerce customer would then use the Connect API to deploy the resulting Connector to their Composable Commerce Project.

Connect applications

Connect applications are the applications which commercetools Connect hosts and runs. You can create Connect applications using JavaScript/TypeScript or Java. The source code of Connect applications is saved in a GitHub repository, and this repository is referenced by a Connector.

Connect applications can be of the following types:

  • Service: perform specific actions using API Extensions or webhooks to other systems.
  • Event: receive events and perform actions asynchronously using Subscriptions.
  • Job: perform tasks on a regular basis. You can schedule job applications using cron expressions.
  • mc-app: create Custom Applications to extend the functionality of the Merchant Center.

In the example use case, these application types would be suited for the following functions:

  • A service application to validate the contents of carts.
  • An event application to send order confirmation emails.
  • A job application to run daily maintenance, updates, or syncs with external systems.
  • An mc-app application to extend the functionality of the Merchant Center.

For more information, see Developing Connect applications.

GitHub repository

The source code of Connect applications must be saved in a GitHub repository and have a Git tag that refers to a specific release. The GitHub repository can be public or private. If the GitHub repository is private, you must grant read access to the connect-mu machine user.

The GitHub repository must have a specific structure, including a connect.yaml file in the root, which details the configuration of the Connect applications. You can view the example structure of a GitHub repository in the Connect Application Starter in JavaScript.


The Connect API uses Connectors to prepare your Connect applications for deployment. Connectors include a reference to the GitHub repository which contains the source code of Connect applications, and application configuration details needed to configure deployments, such as environment variables.

Connectors have two representations in the Connect API:

  • ConnectorStaged: used to create, update, and preview Connectors before submitting them for publishing.
  • Connector: a read-only model that represents a deployable Connector.

Certification process

The certification process verifies the functionality, security, and stability of Connect applications. Connectors must be certified to be publicly available. Certification is not required for private Connectors. For more information about the certification process, see Certification.


Deployments represent how clients integrate Connect applications into their Composable Commerce Project.

Deployments include a reference to a published Connector, and the configuration needed for the Connect applications to work, such as values for environment variables.

commercetools Connect handles provisioning the infrastructure and runtime environment for Deployments. Clients only need to use the Connect API to create the Deployment. If any of the values for application configuration change, then the client can redeploy the Deployment with new values.

Connectors that use third-party services may require that you have a commercial contract with the service provider before deploying the Connector.