# How integrations fit together

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.

In Zen Electron's planning meetings, the words integration, Connector, and Extension are used interchangeably. This page gives each idea its own place.

## The Direct API is the baseline

Calling the [HTTP API](/api) or [GraphQL API](/api/graphql.md) directly is the default integration. Any system that can make an authenticated HTTPS request can push writes to commercetools and pull reads on demand.

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:

```http title="Request: poll for recently modified Orders"
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 `where` value is shown decoded for readability. In a real request, URL-encode it.
- `withTotal=false` skips 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](/api/import-export/overview.md) | Asynchronous, high-volume ingestion that resolves references between resources for you |
| To notice a change, you must poll. | [Subscriptions](/api/projects/subscriptions.md) | 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](/api/projects/api-extensions.md) | Synchronous logic inside the write that can reject or modify it |
| An API integration has no surface for business users. | [Merchant Center customizations](/merchant-center-customizations/overview.md) | 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](/connect/overview.md), or the [Commerce Integration Layer](/learning-integrate-with-commercetools/commerce-integration-layer/extension-types.md) 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.

```mermaid
flowchart TB
 START["Integration requirement"]
 NATIVE{"Built-in first:<br/>does commercetools already do this?<br/><i>Product Search, Discounts, Shipping Methods</i>"}
 STOP["Use the built-in capability"]
 SOT["Source of truth:<br/>which system owns each data domain?"]

 subgraph I["1. Interaction: how and when do systems exchange data?"]
	DIRECT["Direct API<br/>(the baseline)"]
	IMPORT["Import API"]
	SUBS["Subscriptions"]
	EXT["API Extensions"]
	MC["Merchant Center customizations"]
 end

 subgraph R["2. Runtime: where does the code run?"]
	OWN["Your own infrastructure"]
	CONNECT["Connect<br/>service, event, job,<br/>assets, Merchant Center apps"]
	CIL["Commerce Integration Layer<br/>storefront-facing extensions"]
 end

 subgraph L["3. Lifecycle: how is it packaged and shipped?"]
	CONNECTOR["Connector"]
	DEPLOYMENT["Deployment"]
 end

 START --> NATIVE
 NATIVE -->|"yes"| STOP
 NATIVE -->|"no"| SOT --> DIRECT
 DIRECT --> IMPORT
 DIRECT --> SUBS
 DIRECT --> EXT
 DIRECT --> MC
 I --> R
 CONNECT --> CONNECTOR --> DEPLOYMENT
 DEPLOYMENT -. "provisions" .-> CONNECT

 classDef interaction fill:#e8f1fb,stroke:#2266a5,color:#16324a
 classDef runtime fill:#e8f6ef,stroke:#26734d,color:#173d2c
 classDef lifecycle fill:#fff3d6,stroke:#9a6a00,color:#4d3800
 classDef gate fill:#fdecea,stroke:#a52222,color:#4a1616
 class DIRECT,IMPORT,SUBS,EXT,MC interaction
 class OWN,CONNECT,CIL runtime
 class CONNECTOR,DEPLOYMENT lifecycle
 class NATIVE,STOP,SOT gate
```

## Distinctions that are easy to get wrong

The following distinctions cause most of the design mistakes in integration planning:

1. **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.
2. **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.
3. **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.
4. **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.
5. **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](/learning-integrate-with-commercetools/integration-essentials/choose-where-it-runs.md) 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.

## Related pages

- [Area overview page with navigation](/learning-integrate-with-commercetools.md)
- [Previous page: Before you integrate: built-in capabilities and sources of truth](/learning-integrate-with-commercetools/integration-essentials/before-you-integrate.md)
- [Next page: Choose a connection point](/learning-integrate-with-commercetools/integration-essentials/choose-a-connection-point.md)
- [Search documentation and API specs](/search.md)