Connect overview

Learn about the concepts and terminology of Connect.

Ask about this Page
Copy for LLM
View as Markdown

What is Connect

Connect lets you add functionality to your Composable Commerce 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 (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.

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 process

When requesting a preview build or publishing a Connector, the system checks the code quality and security of your Connect applications. These checks include image security analysis, static application security testing (SAST), and software composition analysis (SCA). 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.

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.

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 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.
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.
  • 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 Composable Commerce 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 Connect support team for assistance.