Connect overview

Connect Add-On
Ask about this Page
Copy for LLM
View as Markdown

Learn about the concepts and terminology of Connect.

What is Connect

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

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 your Project using the Connect API, Merchant Center, or CLI.

Who is Connect for

Connect provides advantages to creators (application developers) and clients (commercetools 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.

Connect workflow

The following diagram and steps provide a complete overview of creating and deploying a Connector.

  1. Create Connect applications using JavaScript/TypeScript or Java.
  2. Save the source code of these Connect applications in a GitHub repository.
  3. When ready to test or deploy your Connect applications, create a release in the GitHub repository with a Git tag.
  4. Create or update your Connector.
  5. Create and deploy a preview build.
  6. Publish a production build.

Key concepts of Connect

The following sections explain the key concepts and terminology of Connect.

Connect applications

Connect applications are the applications that Connect hosts and runs. You can create Connect applications using JavaScript/TypeScript or Java. For more information, see Developing Connect applications.
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:

TypeDescriptionExample use case
ServicePerform actions using API Extensions or webhooks.Validate the contents of carts.
EventReceive events and perform actions asynchronously using Subscriptions.Send order confirmation emails.
JobPerform scheduled tasks using cron expressions.Run daily maintenance, updates, or syncs with external systems.
merchant-center-custom-applicationExtend the Merchant Center with Custom Applications.Provide a frontend for modifying the emails sent by the event application.
merchant-center-custom-viewAdd custom functionality to a specific Merchant Center page using Custom Views.Add custom functionality in the context of a specific page within a built-in Merchant Center application.
AssetsHost static assets with CDN capabilities.Host static assets used by the other applications.
For more information on types and their limitations, see deployment information and limitations.

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. connect.yaml contains the configuration details of the Connect applications, including defining environment variables used by the applications. You can view the example structure of a GitHub repository in the Connect Application Starter in JavaScript.

Connectors

Connectors prepare your Connect applications for deployment.
Connectors reference the GitHub repository containing the source code of Connect applications, and include configuration details for defining environment variables.

In the Connect API, Connectors have two representations:

  • ConnectorStaged: used to create, update, and preview Connectors before submitting them for publishing.
  • Connector: a read-only model that represents a published and deployable Connector.
In the Merchant Center, your Connectors are referred to as Organization Connectors.

Create and update Connectors

Depending on if you are using the Connect API or Merchant Center, the process of creating and updating Connectors is different.

Connect API

Merchant Center


If you are creating a new Connector:


  1. Create a ConnectorStagedDraft that references your GitHub repository and Git tag.
  2. Post the ConnectorStagedDraft to the Create ConnectorStaged endpoint. This creates a ConnectorStaged that you can preview and publish.

If you are updating an existing Connector:


  1. Push your code changes to the GitHub repository and create a release with a Git tag.
  2. Update the ConnectorStaged using the Set Repository update action to reference the new Git tag.


If you are creating a new Connector, follow our Merchant Center guide to Create an Organization Connector.

If you are updating an existing Connector:

  1. Push your code changes to the GitHub repository and create a release with a Git tag.
  2. Open the Organization Connector in the Merchant Center, update the Repository tag, and click Save.

Create and deploy a preview build

Preview builds allow you to test the functionality of your Connect applications before publishing the Connector.

Depending on whether you are using the Connect API or Merchant Center, the process of requesting and deploying a preview build is different.

Connect API

Merchant Center


  1. Request the previewable status of the ConnectorStaged using the Preview Connector update action.
    • The system reviews your ConnectorStaged before it becomes previewable. To check the previewable status of your ConnectorStaged, query the Get ConnectorStaged endpoint and check the isPreviewable field.
    • If the isPreviewable field of your ConnectorStaged is true, the preview is successful and you can continue to step 2. If false, fix any issues in your Connect applications, update the ConnectorStaged if needed (for example by using the Set Repository update action), and repeat this step until isPreviewable is true.
  2. Create a DeploymentDraft that includes a reference to the ConnectorStaged. connector.staged must be set to true to deploy a previewable ConnectorStaged.
  3. Post the DeploymentDraft to the Create Deployment endpoint. This creates a Deployment that includes a reference to the ConnectorStaged.


If you are creating a new Connector, follow our Merchant Center guide to Create an Organization Connector.

If you are updating an existing Connector:

  1. Push your code changes to the GitHub repository and create a release with a Git tag.
  2. Open the Organization Connector in the Merchant Center, update the Repository tag, and click Save.
  3. Reopen the Organization Connector in the Merchant Center and click Request preview.
  4. Once the preview is successful, open the Organization Connector and click Deploy on Preview.

Preview builds must pass validation before they can be deployed.

Publish a production build

Connectors must be published before they can be deployed.

Depending on if you are using the Connect API or Merchant Center, the process of publishing Connectors is different.

Connect API

Merchant Center


  1. If the Connector is intended for private use only, update the ConnectorStaged using the publish update action with certification set to false.
    • If the Connector is intended for public use, update the ConnectorStaged using the publish update action with certification set to true.
    • When published, a Connector is created or updated based on the ConnectorStaged.
  2. Create a DeploymentDraft that includes a reference to the Connector.
  3. Post the DeploymentDraft to the Create Deployment endpoint.
    • This creates a Deployment that includes a reference to the Connector.


  1. Open the Organization Connector in the Merchant Center.
  2. If the Connector is intended for private use only, click Publish for private use.
    • If the Connector is intended for public use, click List on Marketplace.
  3. Once the Connector is published, open the Organization Connector and click Deploy on Production.

Production builds must pass validation before they can be deployed.

Validation pipeline

When requesting a preview build or publishing a Connector, the system checks the code quality and security of your Connect applications. The content of the connect.yaml file is also validated. These checks help ensure that Connect applications meet the required standards for running in a production environment.
You can perform the validation process locally using the commercetools connect validate CLI command.

You can check the validation status of a preview build or published Connector using the Connect API or Merchant Center. The Merchant Center provides a complete report of the validation results, while the Connect API provides a summary of the validation status.

Connect API

Merchant Center


  1. Query the Get ConnectorStaged endpoint of the ConnectorStaged.
  2. Check the previewableReport or publishingReport fields of the ConnectorStaged.
    • The isPreviewable field indicates if the ConnectorStaged has passed validation for the preview build.
    • If the status field is Published, the ConnectorStaged has passed validation for publishing.


  1. Open the Connector in the Merchant Center.
  2. The labels Preview Accepted and Published indicate that the Connector has passed validation.
  3. Go to Preview Report or Publish Report to view detailed information about the validation results.

The validation pipeline runs each time a Connector is previewed or published. It executes the following steps and reports their status.

Fetch Connector repository

The pipeline fetches your Connector's Git repository at the configured tag into the Connect build environment.

Connect requires a clean, verifiable copy of your source code. If this step fails, common causes include missing repository access due to permissions, an incorrect repository URL, or a tag that no longer exists. Resolving repository access allows the remaining pipeline steps to run.

Verify Connector

This step validates that the fetched repository is a well-formed Connector. It checks that the connect.yaml file exists, conforms to the Connector specification schema, and that every application declared in connect.yaml has a corresponding source folder. It also ensures/verifies that each Connect application has the proper configuration and source structure for the build process.
Verifying the Connector catches misconfiguration errors early, before executing expensive build runs. Failures point to concrete fixes in your repository layout or connect.yaml, saving debugging time downstream.

Build Connector applications

The pipeline builds each application declared in your Connector into a container image. Applications are built in parallel. This step also resolves shared common modules.

If this step fails, the pipeline skips the security scans. You must fix earlier steps first.

Software composition analysis (SCA)

The SCA step scans your Connector's open-source dependencies and development dependencies. Any critical finding fails the SCA. To pass, you must update the flagged package to a fixed version or remove the dependency.

Static application security testing (SAST)

The SAST step analyzes the source code of your applications and shared libraries against a Connect-specific quality gate. It detects bugs, code-level security vulnerabilities like injection flaws or unsafe API usage, and code smells. Test files and node_modules folders are excluded from this analysis.

This step catches security weaknesses in your written code without executing it. The step fails on critical issues, which must be remediated in your source code before the Connector can be published or deployed.

Certification process

If you are creating a Connector for private use only, then certification is not required.

Certification is only required for Connectors that you want to make publicly available on the Connect marketplace. The certification process verifies the functionality, security, and stability of Connect applications. For more information about the certification process, see Certification.

Deployments

Deployments represent how clients integrate Connect applications into their 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.
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.
You can deploy Connectors using the Connect API, Merchant Center, or CLI.

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

Deployment information and limitations

When deployed, Connect applications have the following behavior based on their application type.

Service

  • Uses HTTP-based exposed endpoints.
  • Application request times out after 5 minutes.
  • Will autoscale based on the number of requests.

Event

  • Uses a message broker service.
  • The event acknowledgment timeout for an application is 10 seconds.
  • Application request times out after 5 minutes.
  • The delivery promise is at-least-once delivery with no ordering guarantees.
  • The message queue discards a message from a Subscription as soon as the message is acknowledged.
    • Unacknowledged messages are retained for 7 days.
  • The message queue will retry the message if the application responds with any other response code than 102, 200, 201, 202, or 204.
    • Push backoff applies if the application responds with too many negative acknowledgments.
  • Will autoscale based on the number of events being processed.

Job

  • Uses a cron-based scheduler service.
  • The default schedule is defined by the properties.schedule cron expression in connect.yaml. You can override it per deployment using the schedule field of DeploymentConfigurationApplication.
  • Application request times out after 30 minutes.

Merchant-center-custom-application

  • Is a hosted React application.
  • Application request times out after 5 minutes.
  • Will autoscale based on the number of requests.

Merchant-center-custom-view

  • Is a hosted React application.
  • The server times out after 5 minutes.
  • Will autoscale based on the number of requests.

Assets

  • Hosts static assets.
  • Application request times out after 5 minutes.
  • CDN capabilities are supported.

Environments

The DeploymentType lets you control which type of environment your ConnectorStaged or Connector is deployed to.
Deployments are made to the sandbox environment by default if no other type is specified. These deployments automatically scale down to zero when they are unused for a while. This can cause timeouts because they require approximately 15 seconds to boot up again.

Sandbox

The sandbox deployment type is the default deployment type for Connectors. It allows you to run your Connector in a non-production environment, such as a development or QA environment.

You cannot deploy a ConnectorStaged to a sandbox environment.

Preview

The preview deployment type lets you test your ConnectorStaged during application development. It allows you to validate your logic and make sure the functionality works as expected.
You must set the ConnectorStaged isPreviewable status to true for preview deployments.

Preview deployments should be deleted as soon as testing is complete. They are only intended to last a short time and scale down to zero.

Production

To deploy in production, your Project must not be a trial.
The production deployment type lets you deploy a Connector, which is already in production or is ready to be in your production environment. Only published Connectors can use the production deployment type.
production provides the highest scalability for optimal performance and stability of the Connector, with already warmed-up instances ready to manage the load at all times.
If you have not previously published your Connector to production, contact your Customer Success Manager or the commercetools support team for assistance.