Learning PathModule

Choose where it runs and how to adopt it

Decide between your own infrastructure and Connect, then build only as much as the requirement needs.

Ask about this Page

Copy for AI

View as Markdown

After completing this page, you should be able to:

Pair connection points with Connect application types and their limits.
Identify when an integration should stay on your own infrastructure.
Describe Connectors, Deployments, and deployment environments.
Choose the lowest step on the adoption ladder that meets a requirement.
Verify whether a marketplace listing is a Connect Connector.

Choose the runtime after you choose the connection point, not before. Then build only as much as the requirement needs: configuring an existing Connector costs far less than building one.

A vendor's marketplace page says its product "integrates with commercetools." Zen Electron's team wants to know whether that's something it can deploy, configure, or would need to build. This page gives the team the questions to ask.

Two runtime options

Every connection point works with either runtime:

Your own infrastructure: any HTTPS endpoint, queue consumer, or scheduler that you operate. You choose the language, hosting, and scaling, and you run it.
Connect: a managed runtime from commercetools. You supply the code, and Connect hosts, scales, and runs it.

For storefront-facing logic and API Extensions, the Commerce Integration Layer can also host your extension code: schema extensions shape what a storefront reads, and Managed API Extensions are API Extensions that the Commerce Integration Layer hosts and registers. It doesn't run Subscription consumers, scheduled jobs, or other integrations that aren't shopper-facing.

Connect application types

Connect runs code as applications, and the application type determines how the application is called. Connect applications lists every type. Three types pair directly with the connection points in this module:

service: answers an API Extension or receives inbound webhooks from external systems. The service type is an HTTPS endpoint, so it isn't limited to API Extensions.
event: consumes notifications from a Subscription. The event type only consumes notifications from commercetools Subscriptions.
job: runs on a schedule, for example to call the Direct API or the Import API.

The merchant-center-custom-application and merchant-center-custom-view types host Merchant Center customizations, and the assets type hosts static files.

Before choosing an application type, compare the workload with the current application behavior and limitations and best practices. Check supported runtimes and Regions as part of the same review.

When to stay on your own infrastructure

Connect suits lightweight, stateless applications. Its guidance on alternatives rules out stateful, compute-heavy, long-running, and bulk batch workloads, such as a backend-for-frontend (BFF) that manages sessions. For a storefront BFF, the Commerce Integration Layer is a commercetools-hosted BFF that manages shopper sessions for you. Otherwise, keep those workloads on your own infrastructure, along with the following cases:

An existing platform with its own deployment, monitoring, and on-call processes that the team prefers to reuse.
A Region that Connect doesn't offer, where you need the integration close to another system.
Vendor-hosted or iPaaS integrations, which run on the vendor's or iPaaS provider's infrastructure.

The Connect lifecycle

If you choose Connect, a Connector carries the code from a repository to a running application in three stages: a ConnectorStaged draft that you preview and publish, the published Connector, which is private to the Projects you name or public after certification, and a Deployment that installs the Connector in one Project with its own configuration values.

A Deployment runs in one of three environments: sandbox, preview, or production. The environment decides latency. A sandbox Deployment scales down to zero when idle, so the next request has a cold start. A production Deployment keeps warm instances ready and requires a Project that isn't a trial. Price the contract shows how a cold start breaks an API Extension.

Connect describes the creator and client roles as tasks, not people; see Who is Connect for. When you build a Connector for your own Projects, you hold both roles.

The adoption ladder

Before you build, climb only as far as you need. Stop at the first step that meets the requirement:

Configure a public Connector. One exists and covers the requirement. Install and configure it.
Prove the gap isn't configuration. Before you decide a Connector falls short, check whether its configuration options close the gap. Many apparent gaps are settings.
Fork or extend. An open-source Connector covers most of the requirement. Fork it, add only the missing behavior, and publish it as a private Connector. This step isn't available for Connectors whose source you can't access.
Build from a template. Nothing suitable exists. Start from the closest template.

The ladder is a learning aid for ordering the decision, not an official commercetools framework. Each step up adds code that your team owns.

Templates as an effort signal

Templates show where commercetools provides a starting point, which reduces the effort at step 4. The templates overview lists the available templates. The Connect CLI offers its own set of --template values, which don't match the documentation pages exactly. Check both when you estimate a build.

Verify that a listing is a Connect Connector

A marketplace listing that says a product "integrates with commercetools" might describe a Connect Connector, a vendor-hosted service, or an iPaaS recipe. Only a Connect Connector can be deployed by Connect.

The primary evidence is the Connect surface itself. If a Connector appears in the Merchant Center Connect tab with an install action, or in the Connect API, Connect can deploy it. The following request searches the Connect API for payment Connectors:

GET https://connect.australia-southeast1.gcp.commercetools.com/connectors/search?integrationTypes=psp&limit=5
Authorization: Bearer {access_token}

{
  "results": [
    {
      "id": "5ab3edcd-9d23-4934-8f48-256805253119",
      "key": "example-payment-connector",
      "name": "Example payment Connector",
      "integrationTypes": ["psp"],
      "certified": true,
      "private": false,
      "repository": {
        "url": "git@github.com:example/payment-connector.git",
        "tag": "v2.4.0"
      },
      "supportedRegions": ["australia-southeast1.gcp", "europe-west1.gcp"],
      "configurations": [
        { "applicationName": "processor", "applicationType": "service" },
        { "applicationName": "enabler", "applicationType": "assets" }
      ]
    }
  ]
}

The request needs an access token with the view_connectors scope. Hosts and authorization lists the Connect scopes.
integrationTypes filters by domain. See IntegrationType for the current values.
certified and private tell you whether the Connector passed certification and who can deploy it.
supportedRegions tells you whether it can run in your Project's Region.
configurations lists the applications and their types, which tells you which connection points the Connector uses.

As secondary evidence, inspect the source if you have access. A Connect Connector's repository has a connect.yaml file at its root, which declares each application. The repository doesn't have to be public: certified Connectors can use private repositories. Don't treat a missing public repository as proof that a listing isn't a Connector.

The following excerpt shows how a connect.yaml file declares three applications:

deployAs:
  - name: free-sample-product-service
    applicationType: service
    endpoint: /free-sample-product-service
    scripts:
      postDeploy: npm run connector:post-deploy
      preUndeploy: npm run connector:pre-undeploy
  - name: new-product-event-app
    applicationType: event
    endpoint: /new-product-event-app
  - name: new-category-cleanup-job-app
    applicationType: job
    endpoint: /new-category-cleanup-job-app
    properties:
      schedule: '0 1 * * *'

applicationType tells you the runtime pairing for each application.
scripts.postDeploy and scripts.preUndeploy run after deployment and before removal. Connectors use them to create and remove Project resources such as Subscriptions and API Extensions.
properties.schedule sets the default schedule for a job. See Configure connect.yaml for every key.

The Deploy and build Connectors module works with a full connect.yaml file, including its configuration.

Worked example: choose a step for each integration

Zen Electron's team picks a runtime and an adoption step for each integration. The letters match the labels from Choose a connection point:

Integration	Runtime	Adoption step	Reason
A. Catalog and stock feed	Connect job or own infrastructure	Step 1, 2, or 3	Depends on whether a public PIM Connector fits. If the initial load of 46,000 Products can't finish within the current job request limit, the team runs it from its own infrastructure.
B. Same-day metro delivery eligibility	Connect service on a production Deployment, or own infrastructure	Built-in, or step 4	The built-in predicate may be enough. If not, no public Connector covers a private postcode service, so the team builds one.
C. Checkout payments	Connect	Step 1	A certified payment Connector exists for the team's PSP.
D. Order confirmation email	Connect event application	Step 4	No public Connector fits Zen Electron's email service provider, so the team builds one from the email template.

For the order confirmation email (D), the team ran the search shown earlier with integrationTypes=email. No result supports Zen Electron's email service provider, and no configuration option closes the gap, so the team stops at step 4. The Deploy and build Connectors module builds the order confirmation email Connector from a template, then installs and operates it the way a Client would.

Key takeaways

Choose the runtime after the connection point. Every connection point works with your own infrastructure or Connect. For storefront-facing logic and API Extensions, the Commerce Integration Layer can also host the code.
Connect service applications answer API Extensions and inbound webhooks. event applications consume Subscriptions, and job applications run on a schedule.
Keep long-running, compute-heavy, stateful, or bulk-batch work on your own infrastructure.
Sandbox Deployments scale to zero. Production Deployments stay warm and require a Project that isn't a trial.
Climb the adoption ladder only as far as needed: configure, prove the gap isn't configuration, fork, then build.
Verify a listing through the Connect surface. A private repository doesn't rule out a Connect Connector.

Choose where it runs and how to adopt it

Decide between your own infrastructure and Connect, then build only as much as the requirement needs.

Two runtime options.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Connect application types.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

When to stay on your own infrastructure.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

The Connect lifecycle.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

The adoption ladder.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Templates as an effort signal.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Verify that a listing is a Connect Connector.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Worked example: choose a step for each integration.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Key takeaways.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Test your knowledge.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}