Learning PathModule

Use the integration guides

Find the guide that owns a requirement, and know where its stages fit in the decisions you made in this module.

Ask about this Page
Copy for AI
View as Markdown

After completing this page, you should be able to:

  • Map the stages of an integration guide to the decisions in this module.

  • Route a requirement to the guide that owns it, including at the boundary between adjacent domains.

  • Use the commercetools-integrations skill with an AI assistant, and verify what it produces.

This module so far taught the decisions. The integration guides apply them to one domain each and own the field lists, flows, and verification steps. This page shows how the guides are organized, shows where to find them, and resolves the boundaries that send learners to the wrong guide. The next page combines your decisions into a landscape plan that routes each flow to one of these guides.

Read a guide as a sequence of decisions

Most integration guides follow the same sequence. Headings vary, and not every guide has every stage, but each stage maps to a decision you already made.

Guide stageWhat the guide asksWhere this module covers it
Define requirementsWhich system owns each data domain, which flows exist, and what limits them. The section ends with an open prompt for constraints that no fixed list anticipates, for example under the heading Record special requirements.Before you integrate and Choose a connection point
Rule out built-in capabilityWhether commercetools already does this. Some guides, such as shipping, promotions, and search, make this a section of its own.Check for a built-in capability first
Choose a pathWhich Connector option to take, in order, and where to stop.The adoption ladder
Design the applicationsWhich Subscriptions, endpoints, and jobs carry each flow.Choose a connection point and Price the contract
BuildHow to configure, implement, and deploy the Connector.Choose where it runs and how to adopt it and the Deploy and build Connectors module
VerifyHow to prove the flows work end to end.The contract obligations (latency budget, idempotency, and failure behavior) tell you what to test. Verify the resource, not the status shows how to prove it for a Connector.
TroubleshootWhich symptoms point to which cause. Several guides include this stage.The symptoms are specific to each domain, so the guides own them. Debug a failed Deployment shows the Connect-side diagnosis that applies to any Connector.

The path stage in a guide mirrors the adoption ladder: check for an existing Connector, prove the gap isn't configuration, then fork or build.

Find the guide for a domain

The Integrations section of the Guides site lists the guides, and each guide owns the implementation details for its domain. To route a data domain to its guide, use the Plan integrations reference, which maps each domain to its typical owner, direction, and canonical guide.

Two guides need a note that the domain map doesn't carry:

  • The CPQ guide is an older guide that doesn't follow the stages above.
  • Set up Platform Insights covers API telemetry for application performance monitoring, not a commerce data domain.

Most guides link back to Integration essentials, many in a self-learning notice near the top. You can move in both directions: from a guide to the reasoning behind a decision, and from this module to a guide's steps.

The transactional email guide is the one that Deploy and build Connectors applies hands-on. That module builds, publishes, installs, and operates a Connector for it, so use it as a worked reference for the build and verify stages of any other guide.

Resolve the boundaries between guides

Route by data domain, not by the name of the system. The following cases send learners to the wrong guide most often.

  • ERP and OMS. The OMS guide owns the post-order lifecycle: Order status, fulfillment, shipments, returns, and steady-state Inventory updates. It applies even when the ERP is the system that manages Orders. The ERP guide owns the data the other guides don't claim, such as contract Prices, B2B accounts, and invoices. When one system plays both roles, follow both guides as separate flows, so a slow catalog job can't delay a status update. See When the ERP owns the Order lifecycle.
  • Product data and ERP master data. The product data guide owns Products, Categories, media, list and base Prices, and the initial Inventory load, even when the ERP is the source. The ERP guide owns contract and customer-specific Prices.
  • Shipping and OMS. When an OMS books the carrier, the OMS guide owns the Delivery, Parcel, and tracking write-back. Follow the shipping guide's write-back only when commercetools calls the carrier directly. Two writers produce duplicate Deliveries.
  • Gift cards and promotions. Stored value that pays for part or all of an Order is a Payment, and the gift card guide owns it. A discount, voucher, or loyalty award that reduces the Cart total is a promotion (see the promotion and loyalty guide), even when the same vendor sells both.
  • Analytics. Platform Insights and Change History aren't data feeds. Capabilities that are often mistaken for commerce analytics explains why, and the analytics guide covers the export.
  • Storefront and BFF flows. When shoppers read or write through a storefront or BFF that composes commercetools and third-party data, use the Commerce Integration Layer documentation. Integrations that aren't shopper-facing, such as scheduled reconciliation or event-driven exports, stay with the domain guides and Connect.

Worked example: route one ERP requirement

Zen Electron's finance lead asks the team to connect the ERP so that account customers see negotiated prices, warehouse counts stay current, and invoices appear in the account. The team splits the request by data domain before choosing a guide:

RequirementData domainGuide
Account customers see negotiated prices.Contract and customer-specific PricesIntegrate ERP
Warehouse counts stay current.Inventory: the initial load, then steady-state updatesThe initial load in Integrate product data, then updates in Integrate an order management system
Invoices appear in the account.Invoices and financial documentsIntegrate ERP

One request routes to three guides. Each row then enters the landscape plan on the next page with its own connection point, contract, and adoption step.

Build with AI

The commercetools AI plugin includes the commercetools-integrations skill. It has 13 sub-areas, one for each of payment, tax, CRM, PIM, OMS, ERP, gift card, transactional email, marketplace, promotion (including loyalty), analytics, search, and shipping. They match the guides above, except that the skill has no CPQ sub-area. For how to build the Connector, the skill defers to the commercetools-connect skill. Extend it with AI uses both on a real Connector. For storefront-facing extensions on the Commerce Integration Layer, use the commercetools-integration-layer skill.
Each sub-area starts with checks like the ones you learned in this module. The skill numbers its ladder from 0 and calls each position a "rung". Step 0 asks whether built-in commercetools capability meets the need, and steps 1 to 4 are the adoption ladder from Choose where it runs and how to adopt it. Step 0 is a real gate only for promotion, search, and shipping. ERP has a variant: whether the data needs replicating at all, or can be read live. The skill doesn't present step 0 as a real gate for the other sub-areas. The skill tells the assistant to check for Connectors live, rather than from memory, and to name the Connector and version it checked. Ask the assistant to report which sub-area and which step it stopped at (the assistant may say "rung"), and compare that answer with the guide.

Skills change between versions. Check the version that your plugin manager shows, and record it with your change.

AI assistance doesn't transfer accountability. You own what you merge. Verify AI output against the guide and the API documentation, to the same standard as code you wrote yourself.

Key takeaways

  • Most integration guides follow one sequence: define requirements, rule out built-in capability, choose a path, design, build, verify, and troubleshoot. Each stage maps to a decision in this module.
  • The path stage mirrors the adoption ladder. Stop at the first step that meets the requirement.
  • Route by data domain, not by system name. The OMS guide owns the post-order lifecycle even when the ERP manages Orders.
  • The product data guide owns list and base Prices. The ERP guide owns contract and customer-specific Prices.
  • Stored value that pays for an Order belongs to the gift card guide. Discounts that reduce the Cart total belong to the promotion guide.
  • The commercetools-integrations skill covers 13 domains. Check its output against the guides and the documentation, because you remain accountable.

Test your knowledge