Most integration confusion comes from mixing up three separate decisions: how systems exchange data, where the integration code runs, and how that code is packaged and shipped. Keep the decisions apart, and each one becomes small.
The Direct API is the baseline
The Direct API has one built-in limitation: commercetools doesn't tell you when something changes. To notice a change, you poll. For example, an external system can periodically query for Orders modified since its last run:
GET https://api.australia-southeast1.gcp.commercetools.com/zen-electron/orders?where=lastModifiedAt > "2026-10-02T00:00:00.000Z"&sort=lastModifiedAt asc&limit=100&withTotal=false
Authorization: Bearer {access_token}
- The
wherevalue is shown decoded for readability. In a real request, URL-encode it. withTotal=falseskips calculating the total count, which improves query performance.- Polling works, but it trades freshness against load. Poll often and you waste requests; poll rarely and you see changes late.
One baseline, four specializations
The other connection points are not competing alternatives to the Direct API. Each one exists because it removes one specific limitation of calling the API directly:
| Limitation of the Direct API | Connection point that removes it | What it gives you |
|---|---|---|
| Writes are synchronous, and you orchestrate the order of dependent resources. | Import API | Asynchronous, high-volume ingestion that resolves references between resources for you |
| To notice a change, you must poll. | Subscriptions | Asynchronous notifications sent to a message queue after a change is saved |
| Your logic runs outside the write, so it can't stop or change it. | API Extensions | Synchronous logic inside the write that can reject or modify it |
| An API integration has no surface for business users. | Merchant Center customizations | A user interface inside the Merchant Center |
When you evaluate a requirement, start from the Direct API and ask which limitation, if any, blocks you. If none does, the Direct API is the answer.
Three concerns
Every integration design answers three questions. Each question has its own vocabulary.
| Concern | Question | Main concepts |
|---|---|---|
| Interaction | How and when do systems exchange data or control? | Direct API, Import API, Subscriptions, API Extensions, Merchant Center customizations |
| Runtime | Where does the integration code run? | Your own infrastructure or Connect, or the Commerce Integration Layer for storefront-facing extensions |
| Lifecycle | How is the code packaged, deployed, and shared? | Connectors, Deployments, and the marketplace |
The boundaries overlap in places. A Deployment, for example, is a lifecycle resource that also causes Connect to provision the runtime. The value of the three concerns is the order they impose: choose the interaction first, then the runtime, and then the lifecycle.
Distinctions that are easy to get wrong
The following distinctions cause most of the design mistakes in integration planning:
- Connect is not required to integrate. Every connection point works from your own infrastructure. Connect is one runtime option. For storefront-facing extensions, the Commerce Integration Layer is another.
- An inbound webhook is not a connection point. When an external system pushes data to you, it calls an endpoint that you host. That endpoint then calls the Direct API or the Import API, which is the actual connection point. Inbound data never arrives through a Subscription; Subscriptions only carry changes that happen inside commercetools.
- Data-model extensibility is not a connection method. Types and Custom Fields, Custom Objects, and States let you store integration data, such as an external ID or a sync status. They don't move data between systems.
- A Merchant Center customization is a different kind of seam. It gives business users a screen. It doesn't replace a data flow, although it often sits on top of one.
- A marketplace listing is not always a Connect Connector. Some listings describe a vendor-hosted service or an iPaaS integration that runs outside Connect. Choose where it runs and how to adopt it shows how to check.
Worked example: one use case through all three concerns
Zen Electron wants to send a branded order confirmation email when an Order is placed, and let staff edit the email template in the Merchant Center. The team traces the requirement through each concern:
| Concern | Decision | Reason |
|---|---|---|
| Interaction | A Subscription to the OrderCreated Message | The email is a reaction after the Order is saved, and it must not slow down checkout. |
| Interaction | A Merchant Center Custom Application for the template | Staff need a screen. This is a separate seam from the email flow. |
| Runtime | A Connect event application to send the email, and a Connect Merchant Center Custom Application for the editor | The team has no existing infrastructure for either. |
| Lifecycle | One Connector containing both applications, and one Deployment of it in Zen Electron's Project | The two applications ship and version together. |
Now change one requirement: reject a Cart if its shipping postcode can't be serviced. Only two decisions change:
- Interaction: an API Extension on Carts, because the rule must stop the write, not react to it.
- Runtime: a Connect service application, or an HTTPS endpoint on your own infrastructure, to answer the Extension.
The lifecycle stays the same. That separation is the point of the three concerns: changing one requirement changes only the decisions it touches.
Key takeaways
- The Direct API is the default integration. Its built-in limitation is that you must poll to notice changes.
- The Import API, Subscriptions, API Extensions, and Merchant Center customizations each remove one limitation of the Direct API.
- Decide the interaction first, then the runtime, then the lifecycle.
- Connect is optional. Inbound webhooks call the Direct or Import API, and Subscriptions never carry inbound data.
- Types, Custom Fields, Custom Objects, and States store integration data but don't move it.