Commercetools Integrations

commercetools integrations

Connecting commercetools to a specific external system: which integration already exists, whether you need one at all, and what the connector for it must actually do. Twelve sub-areas, each owning one integration domain end to end — the decision ladder, the requirements → connect.yaml mapping, the runtime contract, and the verification steps.

This skill is domain-specific. The build side is not here. How a service / event / job application is written, the connect.yaml contract, least-privilege scopes, lifecycle scripts, sync-vs-async idempotency and ack semantics, testing, deployment, and the production-readiness gate are type-agnostic and live in commercetools-connect. Start here to decide what to build for a given vendor; go there for how to build and ship it.

Route to the sub-area first

Do not answer an integration question from this file. Open the matching overview.md — it owns the workflow, the decision ladder, and the traps for that domain.

Not here: the hosted Checkout widget (commercetools-checkout); surface-independent commerce domain logic such as pricing, discount stacking, tax modes, and native shipping modeling (commercetools-commerce-patterns); SDK client setup, auth, and the core data model (commercetools-platform).

The ladder every sub-area walks

The rungs are the same across all twelve; only the rung-0 native capability differs. Stop at the first rung that fits, and present the choice to the user — the rungs are materially different amounts of work.

0. Native commercetools capability — does this need an integration at all? Real for promotion (Product Discounts / Cart Discounts / Discount Codes / Discount Groups), search (Product Search), and shipping (Zones, Shipping Methods, tiered rates, predicates). Rule it out explicitly, with the reason stated.
1. Use a public connector — one exists and covers the requirements → install and configure. Check live, never from memory; name the connector and version you checked.
2. The gap is config, not code — enabled features, credentials, markup, field mappings and fallback behavior are typically connect.yaml values → back to rung 1.
3. Customise / fork — a real gap config can't close, and an open-source connector exists → fork, add only the delta, publish as an Organization connector.
4. Build a new one — nothing exists for this vendor → build from the closest application template.

Verify a candidate is actually Connect-deployable before calling it installable. A vendor listing is frequently the vendor's own hosted service plus glue you write — not something Connect deploys. The full rule, with the checks that settle it: Marketplace listings are not all Connect connectors.

Step 0 — Gather context (required, run first)

Every sub-area opens with the same mandatory grounding step: pull the latest verified documentation as context for you (the agent) before designing anything. Do not skip it, and do not replace it with another tool.

node scripts/docs-search.mjs \
  --query "<terms from the user's request>" \
  --app-name "<current-app ex: claude, copilot, codex>" \
  --model "<current-model>" \
  --skill-name "commercetools-integrations" \
  --limit 10

Run it from this skill's root. scripts/openApi-schemata.mjs and scripts/graphql-schemata.mjs are here too, for confirming request/response shapes from the OAS or GraphQL schema instead of from memory.

What a sub-area contains

Only overview.md and connector-selection.md exist everywhere. The rest is the common shape, not a guarantee — list the sub-area's directory rather than assuming a file exists:

Sub-areas name their files after what the domain actually needs, so several diverge: pim/ uses build-connector.md + data-mapping.md + testing.md, order-management/ uses build-oms-connector.md + sync-architecture.md, and analytics/ uses pipeline-architecture.md — those last two carry the runtime contract in place of a *-contract.md. Others add provider specifics, test harnesses, or public-connector assessments.

Rules that hold across all twelve

• Ask, don't assume. Requirements come before config, and config before code. Direction, source of truth, and what happens when the external system is down are business decisions — get them from the user and record them.
• Check the registry live. Connector availability changes. One you remember may not exist; one you don't may.
• Vendor facts come from the vendor. Their auth, payloads, field names, limits, and sandbox behavior are theirs to document and change — read their current API docs, and for a public connector its repo's connect.yaml and README. Do not write vendor field names from memory.
• Present the ladder; let the user choose the rung. Give a recommendation and its reasoning, then record the decision.
• Hand back for the build. Once the rung is chosen and the applications are designed, the lifecycle, testing, and production-readiness gate are commercetools-connect.