# Plan your integration landscape

A landscape plan records every integration in one place: what it moves, who owns the data, how it connects, where it runs, and which guide to follow. It prevents two owners for the same data, duplicate integrations, and Subscriptions created one at a time until the Project hits its limit.

Zen Electron's chief technology officer asks for one diagram that shows every system, every flow, and who owns each piece of data. This page builds it.

## Define each integration

For each integration in the landscape, record the following attributes:

| Attribute | Question | Example |
| --- | --- | --- |
| Data domains | Which data does it move? | Customer, Order, Price, Inventory, Product, Tax, Payment |
| Source of truth | Which system owns each domain? | The PIM owns product content. |
| Direction | Which way does the data move? | Into commercetools, out of commercetools, or both for different domains |
| Frequency and latency | How often do changes happen, and how soon must they arrive? | Price and stock changes are more frequent and more time-critical than product descriptions. |
| Volume | How much data, at peak and in total? | 46,000 Products in the initial load |
| Connection points | Which connection points does it use? | Import API and Subscriptions |

For implementation-project planning, such as phasing and team responsibilities, see [Plan integrations](/guides/implementation-guide/plan-integrations.md) in the implementation guide.

## Separate initial migration from ongoing integration

An initial migration and an ongoing integration often move the same data, but they need different designs.

### Initial migration

- **Migrate only active or relevant records.** For example, migrate Products that are live or planned for sale, and Customers who are active.
- For data cleansing, selective Order migration, and data that an integration supplies, see [Plan migration of data](/guides/implementation-guide/plan-migration-of-data.md).

### Ongoing integration

- **Move only changes.** Ongoing flows carry new and updated records, which reduces transfer and processing load.
- **Keep price and inventory as separate flows**, even when one system owns both. Each flow can then run on its own schedule and be tuned for its own volume.

## Patterns

The following patterns are recommended practice for common integration shapes.

### Batch

Batch processing transfers data in bulk at scheduled intervals. Use it when the business can accept a delay, for example for a nightly catalog sync or scheduled bulk price updates. The Import API and job runtimes suit this pattern.

### Broadcast

Broadcasting sends one change to many consumers. When an Order is created, the OMS, the email service, and the analytics warehouse might all need to know.

Use one broad Subscription and let the queue service fan the notification out to each consumer, for example with SNS or EventBridge. One Subscription per consumer can exhaust the current [Subscription limit](/api/limit-increase-guidance.md#extensibility-and-eventing-limits), while fan-out avoids the need.

### Aggregation

Aggregation combines data from several sources into one resource, such as a Product with content from a PIM and logistics data from an ERP. Assign the source of truth per Attribute rather than per resource. For the creation process, the Attribute Group permission boundary, and the choice between one consolidating integration and a primary-plus-secondary design, see [Multiple sources of product data](/guides/product-data-integrations.md#multiple-sources-of-product-data).

### Avoid bidirectional sync

Split fields that commercetools owns and fields that another system owns into two one-way flows for different fields, never one bidirectional flow. [Assign a source of truth to each data domain](/learning-integrate-with-commercetools/integration-essentials/before-you-integrate.md#assign-a-source-of-truth-to-each-data-domain) explains why.

### Real-time database replication is not supported

You can't replicate the commercetools database directly into another system. Use the API for real-time access and Subscriptions for change notifications.

### Inventory threshold

To avoid overselling without calling the inventory source of truth on every Order, track Inventory in commercetools with a threshold. This needs Inventory Entries and an [InventoryMode](/search.md?urn=ctp:api:type:InventoryMode) that tracks stock, such as `ReserveOnOrder`. The default mode, `None`, neither checks nor deducts stock. See [Inventory modes](/api/inventory-overview.md#inventory-modes).

Above the threshold, you rely on commercetools stock, which the tracking mode updates as Orders are placed. commercetools doesn't enforce the threshold, so your integration must implement the check. Below the threshold, the integration checks availability with the source of truth before the Order is created.

## Route each domain to its guide

The [Plan integrations](/guides/implementation-guide/plan-integrations.md) reference maps each data domain to its typical owner, direction, and canonical implementation guide. Use that map to route every row in your landscape instead of maintaining a second domain list.

Route by data domain, not by system name. [Use the integration guides](/learning-integrate-with-commercetools/integration-essentials/use-the-integration-guides.md) shows where to find the guides and resolves the boundary cases, such as ERP and OMS, and product data and ERP master data. Apply those rules to every row in your landscape.

## Build your landscape plan

Before you compare your decisions with Zen Electron's completed landscape, create one row for every data flow. Split a requirement into separate rows when different data domains have different owners or move in different directions.

Use the following columns:

| Flow | Data domain and source of truth | Direction and trigger | Frequency, latency, and volume | Connection point | Contract | Runtime and adoption step | Implementation guide |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Name the business flow. | Name the data and the one system allowed to edit it. | State which way data moves and what starts the exchange. | Record normal and peak demand and the maximum acceptable delay. | Start from the Direct API and name any specialization the requirement needs. | State the latency budget, idempotency strategy, and failure behavior. | Choose your own infrastructure or Connect, or the [Commerce Integration Layer](/learning-integrate-with-commercetools/commerce-integration-layer/extension-types.md) for storefront-facing extensions. Then stop at the lowest viable adoption step. | Link the domain guide that owns the implementation details. |

Review the plan with these checks:

- Every data domain has one source of truth, including Attribute-level ownership for aggregated resources.
- No field is synchronized in both directions.
- Every inbound flow names the endpoint that receives it and the API that endpoint calls.
- Every API Extension states whether it fails open or closed and accounts for customer-facing latency.
- Every Subscription consumer handles duplicate and out-of-order notifications.
- Initial migration and ongoing changes are separate flows when their volume or timing differs.
- The runtime can meet the connection point's time and resource limits.

The plan is complete only when another team can explain each decision without scheduling a clarification meeting.

## Worked example: Zen Electron's integration landscape

Zen Electron's team combines its decisions from this module into one landscape:

```mermaid
flowchart LR
 subgraph IN["Send data in, or exchange it both ways"]
	direction TB
	PIM["PIM<br/>Product content"]
	ERP["ERP<br/>Stock"]
	PSP["Payment service provider"]
	OMS["OMS<br/>Orders and shipment status"]
 end

 CT["<b>commercetools Project</b>"]

 subgraph OUT["Called or notified by commercetools"]
	direction TB
	POST["Postcode service"]
	ESP["Email service provider"]
	CRM["CRM"]
	WH["Analytics warehouse"]
	SE["Search engine<br/>Electronics High Tech"]
 end

 PIM -- "A: Import API" --> CT
 ERP -- "A: Direct API" --> CT
 PSP <-- "C: payment Connector" --> CT
 OMS <-- "E: Subscription out,<br/>status webhook in" --> CT

 CT -- "B: API Extension" --> POST
 CT -- "D: Subscription" --> ESP
 CT -- "E: Subscription" --> CRM
 CT -- "E: Subscription<br/>plus backfill job" --> WH
 CT -- "F: Subscription" --> SE
```

Each letter matches an integration in the following table, which adds the runtime, adoption step, and guide for each flow. Letter E groups the omnichannel back-office flows: Orders to the OMS, Customers to the CRM, and the analytics export. The landscape also adds the merchandised search integration (F) that [Before you integrate](/learning-integrate-with-commercetools/integration-essentials/before-you-integrate.md#worked-example-zen-electrons-ownership-map) set aside for later.

| Integration | Data domain and source of truth | Direction and trigger | Connection point | Runtime | Adoption step | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| A. Catalog and stock | Product content: PIM. Stock: ERP. | Inbound; initial bulk load, then changes | Import API for content; Direct API for stock changes | Own infrastructure for the initial load; Connect job for ongoing changes | Step 1 to 3, depending on PIM Connector fit | [Integrate product data](/guides/product-data-integrations.md) for the catalog and the initial Inventory load, then [Integrate an order management system](/guides/oms-integration.md) for steady-state stock changes |
| B. Metro eligibility | Eligibility: postcode service | In-request, on Cart address change | API Extension | Connect service on a production Deployment | Step 4 (or built-in predicate) | [Integrate a shipping carrier or rate service](/guides/shipping-integration.md) |
| C. Payments | Payment processing: PSP | Checkout-driven; PSP webhooks inbound | Defined by the payment Connector | Connect | Step 1 | [Integrate a payment service provider](/guides/payment-integration.md) |
| D. Order confirmation email | Orders: commercetools | Outbound on `OrderCreated` | Subscription | Connect event | Step 4, from the email template | [Integrate transactional email](/guides/connect-email-integration.md), applied hands-on in [Deploy and build Connectors](/learning-integrate-with-commercetools/deploy-and-build-connectors/overview.md) |
| E. Orders to OMS | Orders: commercetools at checkout, then OMS | Outbound on `OrderCreated`; inbound status webhooks | Subscription; your endpoint calling the Direct API | Connect event and service | Per Connector fit | [Integrate an order management system](/guides/oms-integration.md) |
| E. Customers to CRM | Customers: commercetools | Outbound on Customer change | Subscription | Connect event | Per Connector fit | [Integrate a customer relationship management system](/guides/crm-integration.md) |
| E. Analytics export | Orders and Customers: commercetools | Outbound on change, plus scheduled backfill | Subscription; Direct API queries | Connect event and job | Per Connector fit | [Integrate an analytics destination](/guides/analytics-export-integration.md) |
| F. Merchandised search | Product content: PIM, published through commercetools | Outbound on Product publish | Subscription | Connect event | Per Connector fit | [Integrate external search](/guides/search-integration.md) |

The broadcast pattern applies to the omnichannel back-office flows (E). `OrderCreated` feeds the OMS and the analytics warehouse, so one Subscription with fan-out serves both consumers.

The order confirmation email (D) also reacts to `OrderCreated`, but it keeps its own Subscription. Its Connector's `postDeploy` script creates and owns that Subscription, so the email Connector ships and runs independently of the back-office flows. The cost is one more Subscription against the Project limit, which the team accepts. Fan-out applies to consumers that you connect to the same queue.

The plan routes every flow to a guide. The order confirmation email (D) goes to the email guide, which [Deploy and build Connectors](/learning-integrate-with-commercetools/deploy-and-build-connectors/overview.md) applies hands-on.

## Key takeaways

- Record each integration's data domains, source of truth, direction, frequency and latency, volume, and connection points.
- Treat initial migration and ongoing integration as separate designs. Migrate only relevant, clean data, and keep price and inventory as separate ongoing flows.
- Use batch for delay-tolerant bulk data, broadcast with fan-out for one change with many consumers, and attribute-level ownership for aggregation.
- Avoid bidirectional sync. Real-time database replication isn't supported.
- Route Orders to the OMS guide, and ERP-owned back-office data such as contract Prices and invoices to the ERP guide. Route steady-state Inventory updates to the OMS guide too.

## Related pages

- [Area overview page with navigation](/learning-integrate-with-commercetools.md)
- [Previous page: Use the integration guides](/learning-integrate-with-commercetools/integration-essentials/use-the-integration-guides.md)
- [Next page: Learning check](/learning-integrate-with-commercetools/integration-essentials/learning-check.md)
- [Search documentation and API specs](/search.md)