commercetools integrations

Requirements → analytics connector config

The requirement → config map

Latency → app composition

• Streaming (near-real-time): an event app. Register a MessageSubscription to the specific Messages you export (e.g. OrderCreated, OrderStateChanged, CustomerCreated), or a ChangeSubscription on a resource to catch every change. Subscribe to the minimum set — the 50-Subscription-per-Project limit is a soft limit, so don't burn it with one Subscription per message type when a ChangeSubscription covers the resource.
• Batch / backfill: a job (properties.schedule) that queries the API with a lastModifiedAt window + cursor pagination and loads the delta. Also the vehicle for the one-time historical load.
• Optional full-export service: a service endpoint that triggers an on-demand full export (the template's full-export app). Mention it; build it only if the user needs on-demand full loads.

Scopes and secrets

• Least-privilege, read-only. Egress reads commercetools and writes the destination — so the commercetools scopes are read scopes for the domains you export plus manage_subscriptions for the streamer's registration. Never an admin/manage_project client. → commercetools-connect security.md.
• Destination credentials in securedConfiguration — API key / service-account JSON / connection string — never standardConfiguration, never hardcoded. Analytics data includes customer PII; treat destination creds accordingly.

The connect.yaml envelope

Native client provisioning (prefer this)

inheritAs:
  apiClient:
    scopes:
      - manage_subscriptions   # streamer: postDeploy registers the Subscriptions
      - view_orders            # export orders / order Messages
      - view_customers         # export customers (PII — only if in scope)
      - view_published_products # export catalog (use the read scope your domains need)
      # add view_payments / view_stock etc. only for the domains you actually export
  configuration:
    standardConfiguration:
      - key: DESTINATION_DATASET
        description: Warehouse dataset / table (or CDP source id)
    securedConfiguration:
      - key: DESTINATION_CREDENTIALS
        description: Destination API key / service-account JSON / connection string

Note: view_subscriptions is not a valid standalone scope — manage_subscriptions covers read + write. Declaring non-existent view scopes fails client creation. Grant only the view_* scopes for the domains you export — nothing more.

Per-app config

deployAs:
  - name: analytics-streamer        # near-real-time
    applicationType: event
    endpoint: /analyticsStreamer
    scripts:
      postDeploy: npm ci --omit=dev && npm run connector:post-deploy   # registers the Subscriptions
      preUndeploy: npm ci --omit=dev && npm run connector:pre-undeploy
    configuration:
      standardConfiguration:
        - key: CONNECT_SUBSCRIPTION_DESTINATION
          description: "Injected by Connect (GoogleCloudPubSub or SNS)"
  - name: analytics-backfill        # scheduled batch + one-time history
    applicationType: job
    endpoint: /analyticsBackfill
    properties:
      schedule: "0 2 * * *"         # 02:00 daily; or run on-demand for the one-time load

Worked example (Snowflake, build, orders + customers, stream + nightly backfill)

Derived config:

inheritAs:
  apiClient:
    scopes: [manage_subscriptions, view_orders, view_customers]
  configuration:
    standardConfiguration:
      - key: SNOWFLAKE_ACCOUNT
        description: "Snowflake account + database/schema/table"
    securedConfiguration:
      - key: SNOWFLAKE_CREDENTIALS
        description: Snowflake key-pair / PAT for the loader role
deployAs:
  - name: analytics-streamer
    applicationType: event
    endpoint: /analyticsStreamer
    scripts: { postDeploy: "npm ci --omit=dev && npm run connector:post-deploy", preUndeploy: "npm ci --omit=dev && npm run connector:pre-undeploy" }
    configuration:
      standardConfiguration:
        - key: CONNECT_SUBSCRIPTION_DESTINATION
          description: "GoogleCloudPubSub (injected on Connect)"
  - name: analytics-backfill
    applicationType: job
    endpoint: /analyticsBackfill
    properties:
      schedule: "0 2 * * *"

Is a public connector enough? (analytics)

Do the live check anyway — don't answer from memory

1. Search the Connect marketplace and the integration docs (via docs-search / the Knowledge MCP) for the user's destination (e.g. "Segment", "Snowflake", "BigQuery") — not for "analytics".
2. Apply the marketplace-listing rule. Analytics/CDP listings are especially likely to be partner services, SaaS products, or iPaaS/ELT middleware (Fivetran/Airbyte-style loaders, a CDP's own commercetools source) rather than a deployable Connect connector. Confirm a Connect affordance (public repo / connect.yaml / a Connect deploy action) before calling anything install/configure — full rule: Marketplace listings are not all Connect connectors.
3. Name what you checked (connector/product + version) or record "none exists", and confirm the path with the user before building.

The landscape (verify, but this is the shape)

The ladder (stop at the first rung that fits)

Rung 1 — Configure a public connector / native destination integration

Rung 2 — A gap that config can close

Which Messages/domains flow, field-to-column mapping, and destination table/dataset are usually configuration, not code. Re-check the apparent gap against the connector's configuration surface before forking.

Rung 3 — Fork/extend a public connector (only if open source)

Rung 4 — Build from the Product export template (the common case)

• a full-export application (an API endpoint that exports all resources of a Store to an external system) — your backfill/full-load base;
• an incremental updater — an event app that subscribes to Messages and pushes each change to the external system — your streamer base.

Recording the decision

Destination: Snowflake · rung 4 (build) · checked marketplace 2026-08 — no Connect-deployable Snowflake connector; found only ELT loaders (out of Connect scope) · building an event streamer + a nightly backfill job from the product-export template, deduped on resource.id+sequenceNumber.

Analytics destinations — pick the mechanism, don't catalog vendors

The transport underneath (same for every destination)

Categories (route by these, not by brand)

Data warehouses — BigQuery, Snowflake, Redshift, Databricks

• Decision: the default and best-fit analytics destination. Both mechanisms apply — stream events for freshness, batch for history/gap-repair. Land raw event rows into staging keyed on resource.id + sequenceNumber, then model/MERGE downstream.
• What flows: all transactional/state truth — orders, line items, customers, payments, inventory, catalog.
• PII: the warehouse becomes a PII store — minimize columns, and propagate erasure (pipeline-architecture.md → PII).

CDPs — Segment, mParticle, RudderStack, Tealium

• Decision: stream server-side commerce events into the CDP so it can unify profiles and fan out to downstream tools. Check first whether the CDP has its own commercetools source / integration — if it does and it fits, that may be a configure path (rung 1), not a Connect build (connector-selection.md).
• What flows: customer + order events keyed to a stable user id; usually a curated event set, not the full catalog.
• PII: CDPs are identity-centric — consent and identifier mapping matter; carry only permitted fields.

Product / behavioral analytics — Amplitude, Mixpanel, GA4, Snowplow

• Decision: server-side ingestion of commerce events only (e.g. purchase/refund from OrderCreated/order-state Messages). Honesty caveat: GA4 and Mixpanel are client-side-first — their server-side ingestion (e.g. GA4 Measurement Protocol) is limited and event-shaped, not a natural full-data-export target. Don't present them as a warehouse substitute; if the user wants complete history and modeling, route to a warehouse. Snowplow/Amplitude have more first-class server-side ingestion.
• What flows: a small, well-defined set of conversion/behavioral events — not orders-as-rows.
• PII: keep to hashed/consented identifiers per the tool's model.

BI tools — Looker, Tableau, Power BI

• Decision: do not integrate BI with commercetools directly. BI sits on the warehouse, not on commercetools — point the connector at a warehouse (above) and let BI read from there. If the user asks to "connect Tableau to commercetools," redirect: build the warehouse egress, then BI reads the warehouse.
• What flows: nothing directly from commercetools — it reads modeled tables in the warehouse.

Restating the boundaries (so the design doesn't drift)

• Server-side egress only. Client-side behavioral/pixel tracking (GA4 gtag, Google Tag Manager, Segment.js) belongs in the storefront (e.g. commercetools Frontend) with a tag manager — not a Connect connector. A connector can feed server-side ingestion of the same tools, but page-view/click tracking is a storefront concern.
• Not Platform Insights. If the "analytics" the user wants is API latency / error rates / request logs, that's Platform Insights (an Add-On forwarding telemetry to New Relic / Datadog / OpenTelemetry / Dynatrace) — operational APM, not commerce data. Route there, not to a connector.
• Not Change History. The Audit Log / Change History is a governance change log on a separate, rate-limited host — never an analytics feed.

Choosing, in one line

Analytics connector — export commercetools data to an analytics destination

• Streaming (near-real-time): a Connect event app on Subscriptions / Messages — the resource changes, a Message is delivered, you transform and deliver a row.
• Batch (scheduled backfill / periodic load): a Connect job app that queries the HTTP/GraphQL API with a lastModifiedAt window + cursor pagination and loads the delta.

The mistake to internalize first: delivery is at-least-once, so dedup on the destination side — and never build analytics off Change History. A Subscription delivers each Message at least once with no ordering (delivery guarantees); without a dedup key on the warehouse side (resource.id + sequenceNumber) you get duplicate rows. And the Change History / Audit Log is not an analytics feed: it lives on a separate host, is token-rate-limited (429 + Retry-After), and the docs explicitly say to "avoid making API calls in response to an event stream or message subscription" — it is a governance/compliance log, not a high-throughput data source.

Disambiguate "analytics" before designing (three different things)

Fix which one the user means — they route completely differently:

1. Commerce/business analytics (this sub-area). Transactional/state truth (orders, customers, inventory, catalog) flowing out to a warehouse/CDP/analytics tool, server-side. This is what you build here.
2. Platform Insights — an Add-On that forwards commercetools API metrics and server-side logs to an APM (New Relic, Datadog, OpenTelemetry, Dynatrace). This is operational/APM telemetry, not commerce data — if the user wants request latency / error rates, route them here, not to a connector.
3. Change History / Audit Log — a governance/compliance change log (who changed what). Separate host, rate-limited — not an analytics feed (see the blockquote).

Server-side egress only — client-side tracking is out of scope

Workflow

Step 0 — Gather context (required, run first)

node scripts/docs-search.mjs \
  --query "<analytics terms from the user's request, e.g. 'export orders data warehouse subscription messages product export template lastModifiedAt query pagination'>" \
  --app-name "<current-app ex: claude, copilot, codex>" \
  --model "<current-model>" \
  --skill-name "commercetools-integrations" \
  --limit 10

Step 1 — Extract requirements (before any config or code)

1. Which destination, and what kind? A data warehouse (BigQuery, Snowflake, Redshift, Databricks), a CDP (Segment, mParticle, RudderStack, Tealium), a product/behavioral-analytics tool (Amplitude, Mixpanel, GA4, Snowplow), or a BI tool (Looker/Tableau/Power BI — which sits on the warehouse, not on commercetools). The category decides the mechanism — see destinations.md.
2. Which data domains? Orders, carts, customers, payments, inventory, catalog (products/prices) — and which fields. Customer data is PII: name it explicitly so GDPR handling is designed in, not bolted on.
3. Latency — streaming, batch, or both? Near-real-time (event app on Messages) vs periodic load (job querying the API). Most real pipelines need both: a stream for freshness + a batch backfill for history and gap-repair.
4. Historical backfill needed? A one-time (or periodic full) load of existing data is a separate job from the ongoing stream — like a migration.
5. Destination schema / grain. One row per event, or an upserted current-state table? This decides the transform and the dedup/merge key.
6. Volume & throughput. Order/event volume shapes batch page size, backoff, and whether the ~50-Subscription budget is a constraint.
7. Anything special or non-standard? (always ask — open-ended) Multi-project/multi-region consolidation, data residency, real-time personalization needs, existing warehouse loader/ELT tooling (Fivetran/Airbyte-style) the user already runs, retention/erasure policy. Capture each as its own line; don't force it into a slot above.

Step 1.5 — Is a public connector enough? (a hard, ordered gate — do the live check anyway)

1. Check live data. Search the Connect marketplace and the integration docs (via docs-search / Knowledge MCP) for anything targeting the user's destination. Don't answer from memory — the marketplace changes.
2. Apply the marketplace-listing rule. A listing may be a partner/iPaaS/SaaS product, not a deployable Connect connector — see Marketplace listings are not all Connect connectors.
3. Confirm with the user, and only then conclude the rung.

1. A public connector / native destination integration covers it → install + configure. Installation is the commercetools-connect skill's deployment-installation.md.
2. A gap looks like config → prove it (which Messages, field mapping, destination table) before forking → back to rung 1.
3. An open-source connector with a real gap → fork/extend it; hand off to commercetools-connect for the lifecycle.
4. No connector for the destination (the common case) → build from the Product export template and adapt it to your destination. This is the default landing rung. → connector-selection.md, pipeline-architecture.md.

Step 2 — Design the pipeline (the core deliverable)

Step 3 — Build (rungs 3–4), test-first

• Event streamer = an event app subscribing to the relevant Messages → event-applications.md. At-least-once, no ordering: decode the Pub/Sub envelope, re-fetch by id (required on payloadNotIncluded), ack correctly, and emit a stable dedup key.
• Batch/backfill = a job querying the API with lastModifiedAt + cursor pagination → job-applications.md. Checkpoint the window; each unit idempotent.
• Optional full-export service (like the template's full export, or an in-Merchant-Center dashboard via a custom application) = a service app → service-applications.md. Mentioned as an extension, not required.
• Registration of Subscriptions in idempotent postDeploy / preUndeploy → lifecycle-scripts.md.

Step 4 — Deploy

Step 5 — Verify the round trip

References

Adding another destination later reuses this same tree — the two primitives, the dedup model, and the flow don't change; only the destination's delivery API does.

Checklist

Requirements

• Destination named + categorized (warehouse / CDP / product-analytics / BI); data domains + fields listed
• "analytics" disambiguated (commerce data vs Platform Insights vs Change History); client-side tracking flagged out of scope
• Latency decided (stream / batch / both); historical backfill in or out of scope
• Destination schema/grain (event rows vs upserted current-state) and dedup/merge key decided
• PII data domains flagged; retention/erasure policy captured
• Open-ended "anything special?" asked; each special requirement its own line
• Requirements block written and confirmed

Connector fit (decide before building)

• Ran the live marketplace/registry check even though build is expected; applied the listing-isn't-a-connector rule; confirmed with the user
• Ladder rung presented to the user and chosen by them, and recorded: configure (1) · config-closes-gap (2) · fork (3) · build-from-template (4, the default)

Pipeline design (the deliverable)

• Apps chosen: event streamer (event) and/or batch job (job); optional full-export service noted
• Streamer subscribes to only the needed Messages; transform is a pure, tested function
• Dedup key on the destination side (resource.id + sequenceNumber); payloadNotIncluded re-fetch handled
• Batch job windows on lastModifiedAt + cursor pagination + checkpoint
• PII minimized; not logged; least-privilege read scopes; destination creds in securedConfiguration

Build & verify (test-first)

• Built test-first on the commercetools-connect event/job/service references and their checklists
• Subscriptions registered idempotently in postDeploy; cleaned up in preUndeploy
• Round trip verified: one change → one row (no duplicate); batch window loads idempotently

The analytics egress pipeline

The one rule that spans the pipeline: dedup on the destination side

• For notificationType: "Message" → resource.id + sequenceNumber (monotonic per resource; higher wins).
• For Change payloads (ResourceCreated/Updated/Deleted) → resource.id + version (note version is not sequential, but is comparable per resource).

App 1 — the event streamer (event, near-real-time)

• Subscribe to the minimum Messages for the domains you export — register in idempotent postDeploy (lifecycle-scripts.md). A MessageSubscription for specific message types (OrderCreated, OrderStateChanged, CustomerCreated, …) when you want typed, targeted events; a ChangeSubscription on a resource to capture all changes in one Subscription (spends less of the 50-Subscription budget). Message catalogs: Cart & Order, Customer, all Messages. On Connect the broker is injected and follows the deployment region — branch on CONNECT_SUBSCRIPTION_DESTINATION and build the destination from the matching injected vars (CONNECT_GCP_* or CONNECT_AWS_TOPIC_ARN); don't hardcode a broker (event-applications.md, Pattern 7).
• Decode + validate the envelope (base64 message.data → JSON → resource ref → notificationType), and ack correctly (2xx for handled/irrelevant; non-2xx only for a transient delivery/destination failure you want redelivered). Don't 4xx a subscribed-but-unhandled type into a redelivery loop; don't swallow a transient destination outage into silent data loss. → event-applications.md, Patterns 1–3.
• Re-fetch the resource by resource.id — never transform from the Message payload. It can be stale (no ordering) or absent: if a Message exceeds the queue size limit it is delivered with payloadNotIncluded set and no resource data, so re-fetch is mandatory, not optional (event-applications.md, Pattern 5). Fetch current state, then transform.
• Transform to the destination schema (see below) — a pure function, no network, unit-tested without a deployment.
• Deliver + emit the dedup key. Send to the destination's ingestion API with resource.id + sequenceNumber (or version) attached so the destination deduplicates.

App 2 — the batch / backfill job (job, scheduled + one-time history)

• Window on lastModifiedAt. Query only resources changed since the last checkpoint: a where predicate like lastModifiedAt >= :cursor (the documented integration best practice for "query for changes using timestamps"). Far cheaper than re-scanning the whole dataset.
• Cursor-based pagination, not offset. Offset degrades with depth and is capped at 10,000 records; cursor pagination (a stable sort + lastId/timestamp cursor) is consistent at any depth. Place the most restrictive predicate first (performance considerations).
• Checkpoint the window (e.g. the last processed lastModifiedAt + id in a Custom Object) so a restart resumes and a re-run loads only the delta. Each unit idempotent via the same destination dedup key as the stream.
• Two jobs, one shape: a one-time historical backfill (wide window, from the beginning) and an ongoing gap-repair run (narrow window since the last checkpoint). Keep the backfill separate from the stream.
• Not for heavy bulk. Job containers are capped (2 CPU / 4 GB) and the docs advise against jobs for memory-intensive bulk work (job-applications.md). For a large one-time history load, stream page-by-page to the destination (don't buffer the whole dataset), or orchestrate an external batch loader from the job rather than doing the heavy lift in-container.

The event→row transform (the real work)

Mapping a commercetools resource onto a destination schema is where the value is; keep it pure and tested:

• Localized strings, money, nested arrays. commercetools localized strings ({ "en": … }), centAmount/currencyCode money, and nested line-item/address arrays rarely map 1:1 to a flat warehouse column. Decide per field: flatten to columns, keep as a JSON/VARIANT column, or explode line items into a child table.
• Grain. One row per event (append-only fact table, dedup on the key) or one current-state row per resource (MERGE/upsert on resource.id)? This is a destination-schema decision — pin it in Step 1.
• Carry the dedup key as columns (resource_id, sequence_number / version, last_modified_at) so warehouse-side dedup/merge and late-arrival handling are possible.

PII / GDPR (customer data)

• Minimize — export only the fields analytics needs; don't ship full customer profiles by default.
• Never log PII or destination credentials; structured logs carry only identifiers/correlation keys (security.md).
• Propagate erasure. If a CustomerDeleted / anonymization must reach the warehouse (right-to-be-forgotten), subscribe to it and delete/anonymize the destination rows — an analytics warehouse is a common place orphaned PII hides.
• Destination creds in securedConfiguration; least-privilege read scopes only (config-from-requirements.md).

Platform limits & realities to design around

• No Export API — you build the pipeline from Subscriptions + API queries; there is no bulk "dump" endpoint (Import and export).
• ~50 Subscriptions per Project — a soft limit, increasable on request. Prefer a ChangeSubscription per resource over many per-message-type Subscriptions to stay within budget.
• payloadNotIncluded (payload omitted above the queue size limit, often around 256 KB) — re-fetch by id always; never rely on the payload being present (event-applications.md).
• Messages query API is off by default — Messages are not persisted for querying unless you enable the feature in Merchant Center Developer Settings (enable querying Messages). Subscriptions deliver regardless; don't design a poller against the Messages API assuming it's queryable.
• Change History is not the source — separate host, token-rate-limited (429), explicitly not for event-driven/high-throughput use (see overview.md, and Audit Log overview).

Pitfall catalog

Test-first checklist (mirror in the suite)

Event streamer

• Decodes the base64 envelope; validates type; acks irrelevant messages (no loop)
• Re-fetches the resource by id (never transforms from the payload); handles payloadNotIncluded
• Transform is a pure, unit-tested function (localized strings / money / arrays handled)
• Emits the dedup key (resource.id + sequenceNumber / version); duplicate delivery lands one row
• Transient destination failure → non-2xx (redelivered); terminal → ack + DLQ/alert
• No PII in logged output; least-privilege read scopes

Batch / backfill job

• Windows on lastModifiedAt; cursor pagination (not offset)
• Checkpoints the window; a re-run loads only the delta and is idempotent (same dedup key)
• Streams pages to the destination (no whole-dataset buffering); overlap lock + timeout headroom
• Boundary mocked (commercetools API + destination); suite runs with no deployment/secrets

Verify the analytics round trip

Check 1 — one change produces exactly one row (the stream)

• The row appears in the destination with the mapped fields correct (localized strings, money, addresses).
• The dedup key is present (resource.id + sequenceNumber, or version) on the row — this is what makes redelivery a no-op.
• Redeliver the same envelope (or force a redelivery) and confirm the destination still has one row, not two. A second row is the tell that the warehouse-side dedup/merge key is missing (pipeline-architecture.md).

Check 2 — a batch window loads idempotently

• The first run loads the delta; the second run adds no new rows (same dedup key → upsert/no-op).
• The checkpoint advanced, and a run started from the checkpoint fetches only changes since it — not the whole dataset.
• Cursor pagination reached the end of the window (no silent truncation at 10,000 rows — the sign someone used offset).

The traps (behavior that looks like a bug — or hides one)

Trap 1 — no data at all → the Subscription isn't registered

Trap 2 — duplicate rows are expected without a dedup key

Trap 3 — empty/partial rows → payloadNotIncluded, re-fetch missing

Trap 4 — the Messages query API returns nothing → it's off by default

Trap 5 — acked but never landed → silent gap

Verification checklist

• One source change → exactly one destination row; dedup key present
• Redelivering the same envelope adds no second row (idempotent)
• Batch job over a window is idempotent on re-run; checkpoint advances; cursor pagination (no 10,000 cap)
• Subscription confirmed registered (right resource/types, destination matching the injected broker) when nothing arrives
• payloadNotIncluded handled by re-fetch (no empty/partial rows)
• Transient destination failure redelivers; terminal failure DLQ'd — not acked into a gap
• No PII or destination credentials in logs; erasure propagates to the destination (if in scope)

Requirements → CRM connector config

The requirement → config map

Direction → app composition

• commercetools → CRM (outbound): one or more event apps. To catch every customer change, register a ChangeSubscription on the customer resource (delivers ResourceCreated/ResourceUpdated/ResourceDeleted); to sync only specific changes, register MessageSubscriptions to the Customer messages you care about (CustomerCreated, CustomerEmailChanged, CustomerAddressAdded, CustomerDeleted, …). Add OrderCreated if syncing orders. This is the broadcasting events pattern.
• CRM → commercetools (inbound): a service inbound webhook (CRM pushes changes; 5-min timeout, you authenticate the caller) or a job that polls the CRM for deltas on a schedule. Pick webhook when the CRM can push and you need low latency; poll when it can't or when batch is fine.
• Initial migration: a job for the one-time bulk backfill — kept separate from the ongoing sync, as the docs recommend, because backfill and delta need different pagination/throughput handling.

Source of truth and the linking model

• Link every synced pair by a stable key. Store the CRM record id in the Customer's externalId (the field commercetools provides for exactly this — external-system references), or in a Custom Field if externalId is already used. This key is your upsert / idempotency key in both directions — never blind-create.
• When the CRM masters customer data, keep a Customer in commercetools anyway (it owns permissions, Cart/Order ownership, and promotions), and hold CRM-only attributes in Custom Fields marked read-only so storefront/MC edits can't diverge from the master.
• When commercetools masters, the CRM record is downstream; write to it, don't read authoritative fields back.
• Bi-directional is discouraged. If unavoidable, you must assign field-level ownership (which side wins per field) and add self-change filtering to break loops — see crm-contract.md.

The connect.yaml envelope

Native client provisioning (prefer this)

inheritAs:
  apiClient:
    scopes:
      - manage_subscriptions   # outbound: postDeploy registers the Subscriptions
      - view_customers         # outbound: re-fetch the Customer to build the CRM payload
      - view_orders            # outbound: re-fetch the Order (if syncing orders)
      # inbound instead needs:
      # - manage_customers     # upsert Customers coming from the CRM
      # - manage_types         # only if postDeploy creates the Custom Type for CRM fields
  configuration:
    standardConfiguration:
      - key: CRM_BASE_URL
        description: CRM API base URL (or sandbox vs prod toggle)
    securedConfiguration:
      - key: CRM_API_TOKEN
        description: CRM API token / OAuth client secret

Note: view_subscriptions is not a valid standalone scope — manage_subscriptions covers read + write. Declaring non-existent view scopes fails client creation. Grant manage_customers only on the inbound app that actually writes Customers.

Per-app config

deployAs:
  - name: customer-syncer          # outbound example
    applicationType: event
    endpoint: /customerSyncer
    scripts:
      postDeploy: npm ci --omit=dev && npm run connector:post-deploy   # registers the Subscriptions
      preUndeploy: npm ci --omit=dev && npm run connector:pre-undeploy
    configuration:
      standardConfiguration:
        - key: CONNECT_SUBSCRIPTION_DESTINATION
          description: "GoogleCloudPubSub or SNS"
  - name: crm-migration            # one-time backfill
    applicationType: job
    endpoint: /crmMigration
    properties:
      schedule: "0 3 * * *"        # or run on-demand

Worked example (HubSpot, build, commercetools → CRM one-way)

Derived config:

inheritAs:
  apiClient:
    scopes: [manage_subscriptions, view_customers, view_orders]
  configuration:
    standardConfiguration:
      - key: CRM_BASE_URL
        description: "HubSpot API base (sandbox vs prod)"
    securedConfiguration:
      - key: CRM_API_TOKEN
        description: HubSpot private-app token
deployAs:
  - name: customer-syncer
    applicationType: event
    endpoint: /customerSyncer
    scripts: { postDeploy: "npm ci --omit=dev && npm run connector:post-deploy", preUndeploy: "npm ci --omit=dev && npm run connector:pre-undeploy" }
    configuration:
      standardConfiguration:
        - key: CONNECT_SUBSCRIPTION_DESTINATION
          description: "GoogleCloudPubSub or SNS"
  - name: crm-migration
    applicationType: job
    endpoint: /crmMigration

Is a public CRM connector enough?

Check live data first — don't answer from memory

The marketplace changes. Before deciding:

1. Search the Connect marketplace (marketplace.commercetools.com/connectors) and the integration docs via the docs-search script or the Knowledge MCP.
2. Compare the requirements CRM-by-capability (which entities/objects, direction, field mapping, deletion/consent, real-time vs batch).
3. Name the connector and version you checked — or record that none exists — in the requirements block.

The CRM landscape (verify, but this is the shape)

The ladder (stop at the first rung that fits)

Rung 1 — Configure a public connector

Rung 2 — A gap that config can close

Rung 3 — Fork/extend a public connector (only if open source)

Rung 4 — Build for the CRM the user defines (the common case)

• Outbound syncer (event): commercetools message → CRM object upsert, idempotent by externalId (see crm-contract.md).
• Inbound app (service webhook or job poll): CRM record → Customer upsert by externalId, read-only mapped fields.
• Migration job (job): one-time bulk backfill, checkpointed.
• Config + scopes (config-from-requirements.md).

Recording the decision

CRM: HubSpot · rung 4 (build) · checked marketplace 2026-07 — no public HubSpot connector; marketplace has marketing/CDP tools only · building an outbound event syncer + a migration job, CRM-as-master one-way, linked by externalId.

The CRM sync contract

The one rule that spans every app: upsert by externalId, never blind-create

App 1 — the outbound syncer (commercetools → CRM, event)

What triggers it

• ChangeSubscription on customer — fires on ResourceCreated/ResourceUpdated/ResourceDeleted for any customer change. Simplest way to keep a full profile in sync.
• MessageSubscriptions to specific Customer messages (CustomerCreated, CustomerEmailChanged, CustomerAddressAdded, CustomerDeleted, …) when only certain changes should sync, or when you need the message's typed fields.
• Add OrderCreated (a MessageSubscription) if orders map to CRM deals/sales.

The delivery envelope

The payload shape depends on config, so don't hardcode one form (same as any event app):

• Transport wrapper (GCP): { "message": { "data": "<base64>", ... } } — message.data is base64-encoded JSON; decode first.
• Message format: PlatformFormat ({ notificationType, type, resource: { typeId, id }, ... }) or CloudEventsFormat ({ type: "com.commercetools.…", data: { … } }). Read type and resource.id from whichever you get, and validate the type before acting (ack-and-ignore the platform's test/probe messages). See Test an event application locally.

What it must do

• Re-fetch the Customer/Order by id from resource.id — don't trust the payload. At-least-once delivery with no ordering means an older ResourceUpdated can arrive after a newer one; re-fetching the current resource makes the sync converge to the latest state instead of replaying stale deltas.
• Map the resource to the CRM's object model (Customer→Contact/Lead, Order→Deal). Keep the mapping a pure function — no network — so it's unit-testable without a deployment or token.
• Upsert by externalId. If the Customer has no CRM id yet, create the CRM record and write its id back to the Customer's externalId (or Custom Field) with setExternalId/setCustomField. If it has one, update that CRM record. Idempotent on redelivery.
• Ack correctly. Reply with a positive ack (200/2xx; the Connect event contract treats 102/200/201/202/204 as "don't redeliver") for handled and irrelevant-but-acked messages. Return non-2xx only for transient failures you want redelivered.

Self-change filtering (only if bi-directional)

Deletion & PII (GDPR)

• If deletion is in scope, handle CustomerDeleted / ResourceDeleted by deleting or anonymizing the CRM record — an erasure request must propagate, not leave orphaned PII downstream.
• Customer data is PII: sync only the fields you need, keep credentials in securedConfiguration, and never log PII or the CRM token (commercetools-connect's security.md). Carry marketing-consent flags through the mapping so a "do not contact" preference isn't lost.

App 2 — the inbound app (CRM → commercetools)

Two forms; pick per the CRM's capability and your latency need.

Form A — service inbound webhook (CRM pushes)

• Not an API Extension — no Extension is registered; the CRM calls your endpoint directly. The 5-min service timeout applies (not the 2 s extension limit).
• Authenticate the caller — the CRM calls you, so validate its proof (webhook signature / shared secret / JWT) in-app before writing (commercetools-connect's security.md). Never trust an unauthenticated inbound write to Customers. (AuthorizationHeader authentication on an Extension's HTTP destination is the separate mechanism for the reverse direction — commercetools calling your endpoint as an Extension destination — not inbound-caller auth.)
• Upsert the Customer by externalId — look up by the CRM id, update or create. Use manage_customers scope.
• Idempotent — the same webhook may arrive twice; the upsert must be a no-op the second time.
• Read-only mapped fields — when the CRM masters these fields, store them in Custom Fields you treat as read-only elsewhere, so storefront/MC edits don't fight the master.

Form B — job poll (you pull deltas)

• A scheduled job (properties.schedule) that queries the CRM for records changed since the last run, pages through them, and upserts each by externalId.
• Checkpoint the last-synced timestamp/cursor (e.g. in a CustomObject) so a restart resumes and you fetch only deltas, not the whole CRM each run.
• Owns its own overlap locking and 30-min timeout headroom (commercetools-connect job-applications.md).

App 3 — the migration job (one-time backfill)

Cross-cutting: mapping and rate limits

• Mapping is the real work. commercetools localized strings, addresses (array), customer groups, and Custom Fields rarely map 1:1 to a CRM's flat contact schema. Decide per field; keep it pure and tested.
• Rate limits & backoff. CRMs rate-limit hard. Give outbound calls a timeout, retry transient 429/5xx with exponential backoff, and prefer the CRM's batch endpoints for migration.

Pitfall catalog

Test-first checklist (mirror in the suite)

Outbound syncer

• Decodes the base64 envelope; validates type; acks irrelevant messages
• Re-fetches the resource by id (doesn't map from the payload)
• Upserts by externalId; creates-then-writes-back when absent; update when present
• Duplicate delivery is a no-op (idempotent)
• Self-change filtering asserted if bi-directional
• Deletion → delete/anonymize (if in scope); no PII in logged output

Inbound (webhook or job)

• Webhook: rejects unauthenticated/invalid-signature calls (auth matrix)
• Upserts the Customer by externalId; idempotent on repeat
• CRM-mastered fields written as read-only Custom Fields
• Job: checkpoint advances; a re-run fetches only deltas

Migration job

• Pages + checkpoints; resumes mid-run after a simulated failure
• Upsert (not create) so a re-run doesn't duplicate
• Boundary mocked; suite runs with no deployment/secrets

CRM connector — integrate an external CRM (customer-sync-focused)

The mistake to internalize first: pick direction and source of truth before anything else. Almost every CRM-integration failure — duplicated contacts, overwritten edits, infinite sync loops — traces back to not having decided who masters customer data and which way it flows. commercetools' own integration guidance is explicit: pick a single source of truth per data domain, and avoid bi-directional syncs — they carry real conflict and loop risk.

The three shapes (by direction)

Workflow

Step 0 — Gather context (required, run first)

node scripts/docs-search.mjs \
  --query "<CRM terms from the user's request, e.g. 'CRM customer sync subscription CustomerCreated externalId integration patterns'>" \
  --app-name "<current-app ex: claude, copilot, codex>" \
  --model "<current-model>" \
  --skill-name "commercetools-integrations" \
  --limit 10

Step 1 — Extract requirements (before any config or code)

1. Which CRM, and do they have API access? Salesforce, HubSpot, Dynamics 365, Zoho, or another. Account, API credentials/OAuth app, sandbox vs production, and its rate limits.
2. Direction and source of truth? commercetools → CRM, CRM → commercetools, or (discouraged) both. Who masters customer data? This is the single most consequential answer — it decides the app shape and which side's write wins on conflict.
3. Which entities, and mapped to which CRM objects? commercetools Customer → CRM Contact/Lead/Person; Order → CRM Deal/Opportunity/Sales record; Cart → (rarely). Which fields on each side, and how localized names/addresses map.
4. Ongoing sync, initial migration, or both? A one-time backfill of existing customers is a job; ongoing delta sync is an event or webhook/poll — usually both, built separately.
5. Which events trigger an outbound sync? Creation only, or every customer change and OrderCreated too? This maps to the two Subscription flavors: a ChangeSubscription on the customer resource fires on all changes (ResourceCreated/ResourceUpdated/ResourceDeleted); MessageSubscriptions target specific Customer messages (CustomerCreated, CustomerEmailChanged, CustomerAddressAdded, CustomerFirstNameSet, CustomerDeleted, …) when only certain changes matter. → decides which Subscriptions the connector registers.
6. Deletion / GDPR / consent? Must a CustomerDeleted (or anonymize/erasure request) propagate to delete or anonymize the CRM record? Are there marketing-consent flags to carry? Customer data is PII — this is not optional to think about.
7. Volume and latency? Near-real-time (event/webhook) vs batch (nightly job); expected record counts (drives rate-limit and pagination handling). The docs frame the batch-vs-broadcast choice on exactly these axes.
8. Anything special or non-standard? (always ask — open-ended) Multi-brand/multi-store contact separation, B2B accounts/company hierarchies, loyalty tiers or segments flowing in, double-opt-in, region/data-residency. Capture each as its own requirement line; don't force it into a slot above.

Step 1.5 — Is a public connector enough? (decide before wiring or building)

1. Public connector covers everything → install + configure (Step 2). Don't build. Installing it (CLI auth, scopes, deployment create) is the commercetools-connect skill's deployment-installation.md; it is not the connectorstaged flow.
2. A public connector exists, gap looks like a capability → prove it isn't config first. Field mapping, which events sync, and consent handling are often connector settings → back to rung 1. See config-from-requirements.md.
3. A public connector exists with a genuine gap config can't close, and it's open source → fork/extend it; add only the delta and deploy as an Organization connector. Don't rebuild a working connector. Hand off to commercetools-connect for the build/publish lifecycle.
4. No public connector for the CRM (the common case — Salesforce, HubSpot, Dynamics, Zoho, or any CRM the user defines) → build it. There is no CRM template, so scaffold plain event/service/job apps (or start from the closest outbound template — transactional-emails or product-export — and adapt; there is no inbound template). You implement the CRM API calls and the mapping. The exact contract and gotchas are in crm-contract.md.

Step 2 — Derive the config from the requirements

• App composition from direction — which event/service/job apps you deploy, per the table above.
• Least-privilege API-client scopes via inheritAs.apiClient.scopes — outbound needs read scopes (view_customers, view_orders) + manage_subscriptions; inbound needs manage_customers. Don't hand-supply a manage_project admin client.
• Secrets in securedConfiguration — the CRM API token / OAuth client secret is securedConfiguration, never standardConfiguration, never hardcoded. This is customer-PII-adjacent; treat it accordingly.
• The linking model — store the CRM record id in the Customer's externalId (or a Custom Field), and hold CRM-only attributes in Custom Fields marked read-only when the CRM is master.

Step 3 — Price the async contract (reference)

Step 4 — Build/verify the sync apps (the main body of work), test-first

1. Outbound syncer(s) (event) — on a customer change (ChangeSubscription ResourceUpdated/ResourceCreated, or specific Customer messages) or OrderCreated, re-fetch the resource by id, map it to the CRM's object model, upsert by externalId (idempotent), write the CRM id back to the Customer, ack correctly.
2. Inbound app (service webhook or job poll) — authenticate the caller (webhook) or page the CRM (job); upsert the Customer by externalId; set CRM-mastered fields read-only; be idempotent.
3. Migration job (job) — page the source in bulk, upsert deltas, checkpoint so a restart resumes; keep each unit idempotent.

Step 5 — Verify the round trip

References

Adding another CRM later means reusing this same tree — the direction-driven app shapes, the linking model, and the flow do not change; only the CRM's object model and API calls do.

Checklist

Requirements

• CRM chosen + API access/credentials (sandbox vs prod, rate limits) known
• Direction and source of truth decided (one-way preferred; bi-directional only with a stated reason)
• Entity → CRM-object mapping (Customer→Contact, Order→Deal) and field mapping identified
• Ongoing sync vs initial migration (usually both) decided; trigger events listed
• Deletion/GDPR/consent handling decided; PII scope minimized
• Asked the open-ended "anything special?" question; each special requirement its own line
• Requirements block written and confirmed; specials fed into the Step 1.5 fit-check

Connector fit (decide before wiring/building)

• Checked live marketplace + integration docs (not memory); named the connector + version (or confirmed none exists)
• Ladder rung presented to the user and chosen by them: configure (1) · config-closes-gap (2) · fork/extend (3) · build (4)
• For a classic CRM with no connector, recognized this is a build, not a marketplace install

Config (the deliverable)

• App composition matches the direction (event / webhook / poll / migration job)
• Only documented connect.yaml envelope fields; file at the repo root
• inheritAs.apiClient.scopes least-privilege (read + manage_subscriptions outbound; manage_customers inbound)
• CRM credentials in securedConfiguration; toggles/region in standardConfiguration
• Linking model chosen: externalId (or Custom Field) as the stable key; CRM-only fields read-only when CRM is master

The sync apps (build test-first — do not write a function body before its red test)

• Outbound syncer re-fetches by id, upserts by externalId, writes the CRM id back, acks with 200/2xx
• Inbound app authenticates the caller (webhook) / pages the CRM (job); upserts the Customer by externalId; idempotent
• Self-change filtering in place if bi-directional (no loop)
• Deletion/anonymization propagated if in scope
• Boundary mocked; suite runs with no deployment/secrets

Verification

• Counterpart record appears, linked by externalId
• A field update propagates exactly once (no loop)
• Deletion/anonymization propagates (if in scope); no PII in logs

Verify the CRM round trip

Check 1 — the counterpart record appears, linked by externalId

Create a Customer in commercetools (outbound) or in the CRM (inbound), let the sync run (or, locally without Pub/Sub, POST the base64 message envelope to the syncer directly), then:

• The counterpart record exists in the destination (a Contact in the CRM, or a Customer in commercetools).
• The link is set: the commercetools Customer's externalId (or Custom Field) holds the CRM record id — this is what makes the next change an update, not a duplicate. A record that appears with no externalId written back is the tell that the upsert-and-link step is missing; the next sync will create a duplicate.
• The mapped fields match (localized names, address, consent flags).

Check 2 — a delta propagates exactly once (no loop)

Update one field (e.g. last name) on the mastering side and watch the other side:

• The change appears on the counterpart — once.
• No duplicate record is created (proves upsert-by-externalId, not create).
• Watch for a loop. In a bi-directional setup, a missing self-change filter shows up as a burst of writes ping-ponging between the systems (rising API call counts, version numbers climbing on their own). One update should produce one write per direction and then stop. If it doesn't, the self-change filter is missing (crm-contract.md).

Check 3 — deletion / anonymization propagates (if in scope)

The traps (behavior that looks like a bug — or hides one)

Trap 1 — the sync loop (looks fine at first, then floods)

Trap 2 — rate-limit throttling looks like "sync stopped"

Trap 3 — sandbox data quirks

Verification checklist

• Counterpart record created and externalId written back (link established)
• A field update propagates once; no duplicate record created
• One change settles to one write per direction (no loop) — asserted, not just observed
• Deletion/anonymization propagates; no orphaned PII (if in scope)
• No PII or CRM token in logs
• Migration resumes from checkpoint; respects rate limits (batch + backoff)

Requirements → email connector config

The requirement → config map

Scopes — least-privilege depends on which emails you send

Why token emails need write access. The token value is only present in the CustomerEmailTokenCreated / CustomerPasswordTokenCreated Message when the token's validity is ≤ 60 minutes (customer password reset). For longer-lived tokens the value is omitted, so the connector must create the token itself (a POST .../password-token write) — which is what the official template does. If your reset tokens are short-lived and you read the value straight from the Message, view_customers is enough; if you mint in the handler, you need manage_customers.

The connect.yaml envelope

Native client provisioning (prefer this)

inheritAs:
  apiClient:
    scopes:
      - manage_subscriptions   # postDeploy registers the email Subscription
      - view_orders            # handlers re-fetch the Order for order emails
      - manage_customers       # only if minting verification/password tokens; else view_customers

The event app

deployAs:
  - name: mail-sender
    applicationType: event
    endpoint: /mailSender
    scripts:
      postDeploy: npm ci --omit=dev && npm run connector:post-deploy    # registers the Subscription
      preUndeploy: npm ci --omit=dev && npm run connector:pre-undeploy  # deletes it
    configuration:
      standardConfiguration:
        - key: CTP_REGION
          description: commercetools Composable Commerce API region
      securedConfiguration:
        - key: EMAIL_PROVIDER_API_KEY
          description: API key for the email service provider
        - key: SENDER_EMAIL_ADDRESS
          description: Verified sender address shown in the email
        - key: ORDER_CONFIRMATION_TEMPLATE_ID
          description: ESP template id for order confirmation
        # …one template id per email type in scope

Subscription destination is injected, not declared. An event app's queue/topic is provisioned by Connect, which injects CONNECT_SUBSCRIPTION_DESTINATION and CONNECT_GCP_TOPIC_NAME / CONNECT_GCP_PROJECT_ID (or CONNECT_AWS_TOPIC_ARN for SNS) at deploy time. Build the Subscription destination from those in postDeploy — don't add them to connect.yaml and don't hardcode a broker (event-applications.md).

Worked example (SendGrid, from-template build)

Derived config:

inheritAs:
  apiClient:
    scopes: [manage_subscriptions, view_orders, manage_customers]  # manage_customers: mints the reset token
  configuration:
    standardConfiguration:
      - key: CTP_REGION
        description: commercetools Composable Commerce API region
    securedConfiguration:
      - key: EMAIL_PROVIDER_API_KEY
        description: SendGrid API key
      - key: SENDER_EMAIL_ADDRESS
        description: Verified sender (e.g. no-reply@shop.example)
      - key: ORDER_CONFIRMATION_TEMPLATE_ID_EN
        description: SendGrid dynamic template id — order confirmation (en)
      - key: ORDER_CONFIRMATION_TEMPLATE_ID_DE
        description: SendGrid dynamic template id — order confirmation (de)
      - key: ORDER_SHIPMENT_TEMPLATE_ID_EN
        description: SendGrid dynamic template id — shipment (en)
      - key: ORDER_SHIPMENT_TEMPLATE_ID_DE
        description: SendGrid dynamic template id — shipment (de)
      - key: PASSWORD_RESET_TEMPLATE_ID_EN
        description: SendGrid dynamic template id — password reset (en)
      - key: PASSWORD_RESET_TEMPLATE_ID_DE
        description: SendGrid dynamic template id — password reset (de)
deployAs:
  - name: mail-sender
    applicationType: event
    endpoint: /mailSender
    scripts:
      postDeploy: npm ci --omit=dev && npm run connector:post-deploy
      preUndeploy: npm ci --omit=dev && npm run connector:pre-undeploy

Is a ready-made email connector enough?

Do this in order — don't skip, don't answer from memory

1. List the connectors from the live Connect marketplace (marketplace.commercetools.com/connectors) + the email docs via the docs-search script or the Knowledge MCP — the email / messaging / marketing listings.
2. Present them to the user: name · vendor · service · certification/status, and flag whether any is a transactional email connector or only marketing/CRM platforms.
3. Confirm the approach with the user — use as-is (rung 1) · config-closes-gap (rung 2) · modify/fork (rung 3) · create from template (rung 4). Do not presume the rung.
4. Record platform/ESP · rung · connector + version checked · why.

The email landscape (verify, but this is the shape)

The ladder (stop at the first rung that fits)

Rung 1 — Configure a ready-made connector

Rung 2 — A gap that config can close

Rung 3 — Fork/customize (the "customize the code" path)

Rung 4 — Build from the template (the "create a new one" path)

What you actually write on rung 4:

• The ESP send call in sendMail: template id + to/from + personalization data → the provider's transactional-send API (providers.md).
• Your delivery-semantics choice (ack-first vs ack-after-success + dedupe) and any retry (email-contract.md).
• Localization, state-filtering on order-state emails, and token-email handling if in scope.
• Config + least-privilege scopes (config-from-requirements.md).

Recording the decision

Email: SendGrid · rung 4 (build from template) · checked marketplace 2026-07 — no dedicated SendGrid email connector listed; using the official transactional email template and implementing the SendGrid dynamic-templates send call · emails: order confirmation + shipment + password reset.

The one-app email contract

What triggers it — one Subscription, several message types

The canonical message set (grounded in the template) and what each email is:

What the handler must do

1. Decode & validate the envelope, then branch on Message type to the right email (the template uses a handler factory). Ack anything you don't handle (see the delivery-semantics section, and event-applications.md).
2. Re-fetch the resource by id — getOrderById(message.resource.id), getCustomerById(order.customerId). Don't trust the payload: it can be stale (no ordering) or omitted (payloadNotIncluded). The template does this correctly. Token emails are the exception (below).
3. Build the personalization data (recipient, name, order lines, totals) and pick the template id for the email type (and locale).
4. Send via the ESP (providers.md) behind a tight timeout — the event ack timeout is 10 s; a hung ESP call must abort, not stall the handler.

The central decision: delivery semantics for a non-idempotent send

Option A — ack first, then send (at-most-once; the template's default)

response.status(HTTP_STATUS_SUCCESS_ACCEPTED).send(); // 202, immediately
// …then decode, route, re-fetch, sendMail — errors only get logged

• Guarantees: never double-sends on redelivery (the message is already acked).
• Cost: a transient ESP failure (or a throw) silently drops the email — the platform will not redeliver. Fire-and-forget.
• Use when a duplicate is worse than a miss, or you add your own retry/DLQ around the send.

Option B — send, then ack on success (at-least-once + dedupe)

Ack only after the ESP confirms; return non-2xx on a transient failure so the broker redelivers:

try {
  await sendMail(...);           // confirmed accepted by the ESP
  res.status(204).send();        // ack — safe to stop
} catch (err) {
  if (isTransient(err)) { res.status(503).send(); return; }  // redeliver
  res.status(200).send();        // permanent: ack + alert, don't loop
}

• Guarantees: transient failures retry — the email eventually goes out.
• Cost: redelivery will re-send unless you dedupe. Email sends aren't idempotent at the platform, so make them so:
  • ESP idempotency key — pass a stable key (e.g. resource.id + sequenceNumber, or the message id) so the ESP collapses duplicates (providers.md — SendGrid, others support this).
  • or a sent-marker — record "sent" on a stable key the target can check before re-sending (a Custom Field/Custom Object), re-checking live state — never an in-process set (event-applications.md).

Token emails (verification & password reset) — the value isn't always in the Message

• Read from the Message — create tokens with ≤ 60-min validity so the value is present; view_customers is enough. Simplest, and the emailed token is the one the user's action created.
• Mint in the handler — call POST .../password-token (or email-token) yourself and email that value (what the template does). Works for any validity, but needs manage_customers (a write), and the emailed token differs from the triggering one. Under at-least-once this also means a redelivery mints another token — dedupe, or accept that older tokens stay valid until used (creating a token doesn't invalidate older ones by default).

Never log the token value (PII/secret) — see hygiene below.

Order-state emails must be gated on the target state

const order = await getOrderById(id);
if (order.shipmentState !== "Shipped") return ack(); // only the shipment email
// or: if (order.orderState !== 'Cancelled') return ack();

Localization

• Read the language from customer.locale (fallback: order/store locale, then a default).
• Resolve localized strings from LocalizedString fields (lineItem.name[locale]) with a fallback, and pick a locale-specific template id (or pass the locale to the ESP if the template branches internally).

Hygiene: PII, consent, deliverability

• Don't log PII or tokens. The template logs full message bodies and email addresses; scrub recipient addresses, names, and any token value from logs (log the resource.id/sequenceNumber correlation key instead). → security.md, observability-operations.md.
• Keep it transactional. Transactional emails (order/account/token) generally don't require marketing opt-in; marketing/promotional email does and belongs in a marketing platform, not this connector. Don't quietly turn a transactional connector into a marketing sender.
• Sender must be verified. SENDER_EMAIL_ADDRESS must be a verified sender/domain in the ESP or mail is rejected or spam-filed.
• Bounces/complaints are the ESP's to report. If you need them reflected back into commercetools, that's a separate inbound-webhook service app consuming the ESP's event webhook — out of scope for the sender.

Pitfall catalog

Test-first checklist (mirror in the suite)

• Decodes the base64 envelope; validates & branches on message type; acks unhandled types
• Delivery semantics asserted — ack-first or ack-after-success + dedupe; the failure path proven (no silent drop / no double-send for the chosen mode)
• Re-fetches Order/Customer by id; handles payloadNotIncluded
• Order-state/shipment emails gated on the target state (asserted)
• Correct template id + recipient + personalization data per email type; money/date formatting
• Localization picks the right template/strings from customer.locale with fallback
• Token email: value sourced correctly (Message ≤60 min, or minted) and never logged
• postDeploy registers only the needed message types, idempotently; boundary mocked; suite runs with no deployment/secrets

Email connector — integrate a transactional email service (event-driven)

• mail-sender (an event app driven by a Subscription on Customer/Order Messages) — commercetools delivers a Message to the app's queue; the handler picks the email type from the Message type, re-fetches the resource, builds the personalization data, and calls the ESP to send. Email is always asynchronous: sending must never block or fail a checkout, so there is no API Extension here.

The mistake to internalize first: delivery semantics. An ESP send is not idempotent — call it twice and the customer gets two emails. Event delivery is at-least-once, so the same Message will sometimes arrive twice. How you acknowledge decides everything: ack before sending (at-most-once — never double-sends, but a transient ESP failure silently drops the email) vs. ack after a confirmed send and dedupe on redelivery (at-least-once — retries failures, but you must dedupe or customers get duplicates). The official template acks first (fire-and-forget). Pick deliberately per email type — see email-contract.md.

Workflow

Step 0 — Gather context (required, run first)

node scripts/docs-search.mjs \
  --query "<email terms from the user's request, e.g. 'transactional email connector subscription messages order confirmation customer registration'>" \
  --app-name "<current-app ex: claude, copilot, codex>" \
  --model "<current-model>" \
  --skill-name "commercetools-integrations" \
  --limit 10

Step 1 — List the publicly available connectors (required — do this first, before ESP or requirements)

Step 2 — Confirm the approach: use, modify, or create (required — do not skip, do not assume)

1. Use a public connector as-is (rung 1) → install + configure it; the emails are authored and sent inside that platform. Installation (CLI auth, scopes, deployment create) is the commercetools-connect skill's deployment-installation.md.
2. Modify / fork an existing connector (rung 3) → the "customize the code" path: fork a source-available connector or the official template, add only the delta (message types, localization, attachments, a different ESP), deploy as an Organization connector. (First rule out rung 2 — a gap that config can close.)
3. Create a new one from scratch (rung 4) → build from the transactional email template, implementing the stubbed ESP call for the service they define.

Email is template-first: unlike tax (where Avalara/Vertex ship certified connectors), most ESPs have no dedicated transactional connector, so "create new" or "modify the template" is the common outcome — but you still run Steps 1–2 and let the user decide; never skip the fit-check or presume the rung.

Step 3 — Extract requirements (after the approach is chosen)

Which emails, on which events, in which language, is downstream of business facts. Each maps to a config key in Step 4 or a decision in the contract. Ask the user (don't assume):

1. Which ESP, and why? SendGrid, Mailgun, AWS SES, Postmark, Brevo, Mailchimp/Mandrill, … Do they already have an account + API key + a verified sender domain? (Deliverability, template model, and pricing differ; see providers.md.)
2. Which emails do they need? Each maps to a commercetools Message — the canonical set the template covers: registration (CustomerCreated), email verification (CustomerEmailTokenCreated), password reset (CustomerPasswordTokenCreated), order confirmation (OrderCreated), order state / shipment (OrderStateChanged, OrderShipmentStateChanged), refund/returns (ReturnInfoAdded, ReturnInfoSet). See email-contract.md.
3. For order-state emails, which target states trigger a send? OrderStateChanged fires on every transition — you only want to email on specific ones (e.g. Confirmed, Cancelled, shipmentState Shipped). Without a state gate you spam customers on every internal state change.
4. Delivery guarantee per email: is a duplicate email acceptable, or is a dropped email worse? Token/reset emails are high-stakes (a dropped reset email blocks the user); marketing-ish confirmations tolerate at-most-once. → drives the ack strategy (email-contract.md).
5. Templating & localization. Are templates authored in the ESP (dynamic/stored templates, referenced by ID — the template's model) or rendered in the connector? Multiple languages? What's the language source — customer.locale, the order/store locale, or a single default? (The template hardcodes en-US — a gap to close.)
6. Region and project? e.g. europe-west1.gcp, project my-project.
7. Token-email validity. For verification/reset emails: the token value only rides the Message when the token's validity is ≤ 60 minutes; otherwise the connector must mint the token itself (a write). → scope + design impact, email-contract.md.
8. Anything special? (always ask — open-ended) Multi-store/brand (different sender/template per store), B2B/business-unit recipients, attachments (PDF invoice), unsubscribe/consent handling, bounce/complaint feedback back into commercetools, a batch/digest email (a separate job app). Capture each as its own requirement line; don't force it into a slot above.

Step 4 — Derive the config from the requirements

• Least-privilege scopes via inheritAs.apiClient.scopes (not hand-supplied CTP_CLIENT_ID/SECRET). Which scopes depends on which emails: always manage_subscriptions (postDeploy registers the Subscription); view_orders/view_customers to re-fetch for order/registration emails; manage_customers if token emails mint a token.
• Secrets in securedConfiguration: ESP API key, and (per template) the per-email template IDs; region and toggles in standardConfiguration.

Step 5 — The Subscription & message routing (reference)

Step 6 — Build the one app (the main body of work), test-first

1. Subscription registration (postDeploy) — idempotent (delete-then-create by a stable key, or get-then-skip); the exact message types; destination from the injected vars for the broker CONNECT_SUBSCRIPTION_DESTINATION reports.
2. The handler — decode the base64 envelope; validate & branch on Message type; ack per your chosen delivery semantics; re-fetch the Order/Customer by id; map to the ESP's send request (template id + personalization data); call the ESP behind a tight timeout.

Step 7 — Verify the round trip

References

Checklist

Connector fit-check (do this FIRST — do not skip or reorder)

• Listed the live marketplace connectors (not from memory) and presented them to the user with name · vendor · service · status
• Flagged whether any is a transactional email connector or only marketing/CRM platforms
• Confirmed the approach with the user: use as-is (1) · config-closes-gap (2) · modify/fork (3) · create from template (4) — before gathering ESP/build details
• Recorded platform/ESP · rung · connector + version checked · why

Requirements (after the approach is chosen)

• ESP/platform chosen + API key + verified sender domain; region + project
• The exact emails/Messages listed; for order-state emails, the target states that trigger a send named
• Delivery guarantee decided per email (duplicate-tolerant vs drop-intolerant) — for use-as-is, owned by the platform
• Templating model (ESP-hosted by ID vs in-connector) and localization source identified
• Token-email validity (≤ 60 min → value in Message; else mint in connector) understood
• Asked the open-ended "anything special?" question; each special its own line
• Requirements block written and confirmed

Config (the deliverable)

• inheritAs.apiClient.scopes least-privilege for the emails in scope (manage_subscriptions + the read/write the handlers need)
• ESP key + template IDs in securedConfiguration; region/toggles in standardConfiguration
• connect.yaml at the repo root; only documented envelope fields

The one app (build test-first)

• Subscription registered idempotently on only the needed message types; destination from the injected vars for the broker CONNECT_SUBSCRIPTION_DESTINATION reports
• Ack strategy implemented and asserted (no silent drop; no double-send)
• Order-state emails gated on the target state; handlers re-fetch by id
• Boundary mocked; suite runs with no deployment/secrets

Verification

• Each event produces an email to the right recipient with the right template + data
• Understood: no Subscription → no email; ESP sandbox/test mode may not deliver

Email service provider specifics

The shape (ESP-agnostic)

Every transactional ESP send is the same four things:

1. Auth — the API key from EMAIL_PROVIDER_API_KEY (secured config), typically a Bearer header.
2. From/To — SENDER_EMAIL_ADDRESS (a verified sender) → the recipient (order.customerEmail / customer.email).
3. A template reference — the ESP-hosted template id for this email type (+ locale), from secured config.
4. Personalization data — the key/value object your handler built (order number, name, line items, totals, token/link) merged into the template by the ESP.

Providers

SendGrid (dynamic templates)

• Send: POST https://api.sendgrid.com/v3/mail/send, Authorization: Bearer <key>.
• Template: template_id (a dynamic template d-…); personalization goes in personalizations[].dynamic_template_data.
• Idempotency: SendGrid supports a batch/idempotency mechanism; at minimum set a stable custom arg / batch id to help dedupe.
• Docs: SendGrid Mail Send.

// sendMail body sketch
{
  from: { email: senderEmailAddress },
  personalizations: [{ to: [{ email: recipient }], dynamic_template_data: data }],
  template_id: templateId,
}

Mailgun (stored templates)

• Send: POST https://api.mailgun.net/v3/<domain>/messages, HTTP basic auth (api:<key>), form-encoded.
• Template: template = the stored template name; variables via h:X-Mailgun-Variables (JSON) or v: params.
• Docs: Mailgun sending.

AWS SES (templated email)

• Send: SendTemplatedEmail / SendBulkTemplatedEmail (SDK v3) or the SESv2 SendEmail with a Template.
• Template: Template name + TemplateData (JSON string); auth via the app's AWS credentials (secured config).
• Docs: SES send templated email.

Postmark (templated, transactional-first)

• Send: POST https://api.postmarkapp.com/email/withTemplate, X-Postmark-Server-Token: <key>.
• Template: TemplateId or TemplateAlias + TemplateModel; separate message streams for transactional vs broadcast.
• Docs: Postmark templated email.

Cross-provider summary

Checklist

• sendMail implemented against the chosen ESP's transactional-send API; key from EMAIL_PROVIDER_API_KEY
• Sender is a verified domain/sender in the ESP
• ESP-hosted template referenced by id (per email type, per locale) unless rendering in-connector is justified
• Personalization data mapping is a pure, unit-tested function; only the HTTP/SDK call is provider-specific
• Idempotency key passed on the send when using at-least-once delivery (dedupe — email-contract.md)
• Outbound call has a tight timeout under the 10 s event ack budget

Verify the email round trip

Check 1 — the Subscription exists and points at the connector

• Query Subscriptions and confirm one exists for your key with the expected messages (resourceTypeId + types) and a destination pointing at the deployed app.
• If it's missing, postDeploy didn't run or failed — check the deployment logs. This is the number-one "nothing happens" cause.

Check 2 — each event produces the right email

The traps (correct-looking behavior that is a bug, or vice-versa)

Trap 1 — ESP sandbox / test mode accepts but doesn't deliver

Trap 2 — duplicate emails (at-least-once without dedupe)

Trap 3 — silent drops (ack-first + a failing send)

Trap 4 — an email on every state change

Trap 5 — empty reset/verification links

Verification checklist

• Subscription registered with the expected message types and destination (else: no email at all)
• Each in-scope event produces a send visible in the ESP feed to the right recipient
• Right template, right language, real data rendered (no empty placeholders)
• Order-state/shipment emails fire only on the target state
• Reset/verification links actually work (token present and valid)
• Delivery confirmed on a live key to a real inbox (sandbox/test mode may not deliver)
• No duplicates under redelivery; no silent drops on transient ESP failure
• No PII/token values in logs

Requirements → gift card connector config

The requirement → config map

The commercetools connection block

standardConfiguration:
  - key: CTP_PROJECT_KEY
    description: commercetools project key
    required: true
  - key: CTP_AUTH_URL
    description: commercetools Auth URL
    required: true
    default: https://auth.europe-west1.gcp.commercetools.com
  - key: CTP_API_URL
    description: commercetools API URL
    required: true
    default: https://api.europe-west1.gcp.commercetools.com
  - key: CTP_SESSION_URL
    description: Session API URL
    required: true
    default: https://session.europe-west1.gcp.commercetools.com
  - key: CTP_CLIENT_ID
    description: commercetools client ID (scopes below)
    required: true
  - key: CTP_JWKS_URL
    description: JWKs URL for JWT validation
    required: true
    default: https://mc-api.europe-west1.gcp.commercetools.com/.well-known/jwks.json
  - key: CTP_JWT_ISSUER
    description: JWT issuer for JWT validation
    required: true
    default: https://mc-api.europe-west1.gcp.commercetools.com
securedConfiguration:
  - key: CTP_CLIENT_SECRET
    description: commercetools client secret
    required: true

Scopes

manage_payments  manage_orders  view_sessions  view_api_clients  manage_checkout_payment_intents  introspect_oauth_tokens

• manage_payments — the processor creates and updates the Payment (redeem transactions).
• manage_orders — associate the Payment with the Order / read order context.
• view_sessions + introspect_oauth_tokens — validate the Checkout Session on /balance and /redeem.
• view_api_clients — resolve the calling client during session/JWT validation.
• manage_checkout_payment_intents — accept POST /payment-intents/:id calls from the Payment Intents API (refund/reverse). Automated reversals additionally require the connector to support the reversePayment action.

The connect.yaml envelope

deployAs:
  - name: enabler
    applicationType: assets
  - name: processor
    applicationType: service
    endpoint: /
    configuration:
      standardConfiguration: [ ... CT block + currency + system config ... ]
      securedConfiguration:  [ ... CT client secret + system secret ... ]

Worked example (build from template, in-house gift card ledger)

Derived processor config (CT block from above, plus):

standardConfiguration:
  - key: GIFTCARD_CURRENCY
    description: Currency this deployment handles (EUR)
    required: true
  - key: GIFTCARD_API_URL
    description: Base URL of the store-credit ledger API
    required: true
securedConfiguration:
  - key: GIFTCARD_API_KEY
    description: Store-credit ledger API key
    required: true

Use it, customize it, or build it?

Check live data first — don't answer from memory

Supported systems and connectors change. Before deciding:

1. Search the Connect marketplace (via the Merchant Center Connect view) and the gift-card docs via the docs-search script or the Knowledge MCP. Filter for Public Connectors of type Gift Cards.
2. Compare the requirements system-by-capability (balance, redeem, partial redemption, multiple cards, refund/reverse, currency, region).
3. Name the connector and version you checked, and record it in the requirements block.

The gift card landscape (verify, but this is the shape)

The ladder (stop at the first rung that fits)

Rung 1 — Use a public connector directly (Voucherify; sample for PoC)

Rung 2 — A gap that config can close

Rung 3 — Customize/fork the public connector (Voucherify)

Rung 4 — Build a new one from the gift card template (the common case)

What you actually write on rung 4:

• The processor balance/redeem logic: code → your system's balance/redeem API, response → the commercetools Payment transaction (see giftcard-contract.md).
• The processor post-order operations (modifyPayment): refund/reverse against your system, if in scope.
• The enabler UI for capturing the gift card code (and PIN, if the system needs one).
• Config + scopes (config-from-requirements.md).

Recording the decision

Gift card: Voucherify · rung 1 (use) · checked marketplace 2026-07 — Voucherify public connector present and covers balance/redeem/refund for our single-currency (EUR) store · configuring it, paired with the existing Adyen PSP integration.

Gift card: in-house store-credit ledger · rung 4 (build) · checked marketplace 2026-07 — no public connector for our ledger · building both apps from the gift card template, paired with the existing Stripe integration.

The two-app gift card contract

The rule that frames everything: never ship alone

App 1 — the processor (service, endpoint /)

Routes and their auth (the auth split is the thing to get right)

Balance

• Take { code } (and PIN/security code if the system requires one), call the gift card system's balance API, and return the balance plus whether it's sufficient for the current cart. Checkout surfaces this to the shopper via the gift_card_balance_success Message (amount, isBalanceSufficient).
• Balance is a read — it must not redeem or reserve value. A common bug is redeeming on the balance call.
• Handle zero/invalid/expired codes cleanly → gift_card_balance_error, so the shopper can try another card or method.

Redeem

• Take { code, redeemAmount }, redeem redeemAmount against the system, and record it on the commercetools Payment as a transaction (the processor owns the Payment). Checkout emits gift_card_redeem_success on success.
• Partial redemption is the norm. If the balance is less than the cart total, redeem the available amount and leave a remainder — the fallback PSP integration covers it. Redeeming a card must not assume it settles the whole cart.
• Multiple cards: a cart may redeem several cards in sequence, each reducing the outstanding amount. Each redeem is its own transaction on the Payment.
• Be idempotent. A retried redeem (network hiccup, double-submit) must not double-charge the card. Key redemption on a stable identifier (the code + amount + payment/cart context, or the system's own idempotency key) so a replay is a no-op, and reconcile against the Payment's existing transactions before adding another.

Post-order operations (/payment-intents/:id)

• Refund and reverse/rollback happen after the Order exists, through the Payment Intents API → modifyPayment. This returns redeemed value to the card (refund) or unwinds a redemption (reverse).
• Automated reversals require the connector to declare support for the reversePayment action; implement it only if the requirements include automatic unwinding of authorized-but-not-completed payments.
• These operations update the Payment's transactions to reflect the new state; keep them idempotent on the intent/operation id.

Keep the mapping pure and testable

App 2 — the enabler (assets)

Pitfall catalog

Test-first checklist (mirror in the suite)

Processor

• /balance is read-only, session-authenticated; reports amount + sufficiency; handles zero/invalid/expired codes
• /redeem session-authenticated; records the redeem transaction on the Payment
• Partial redemption leaves the correct remainder; multiple cards accumulate transactions
• Redeem is idempotent — a replayed request is a no-op (asserted)
• /payment-intents/:id refund/reverse JWT/OAuth-authenticated; produces the right transaction (if in scope)
• Boundary (gift card system, CT APIs) mocked; suite runs with no deployment/secrets

Enabler

• Renders code (and PIN) input; carries only the session; holds no secrets
• Calls /balance then /redeem; surfaces balance/redeem errors to the shopper

Gift card connector — integrate a gift card management system

• processor (a service) — the backend middleware to the gift card system. It checks balances, redeems value, and owns the commercetools Payment object (creates it, adds/updates transactions). Its behavior is driven by its connect.yaml config; it authenticates callers with a Checkout Session (balance/redeem) or a JWT/OAuth token (post-order operations via the Payment Intents API).
• enabler (an assets bundle) — a browser JS library that renders the gift-card input UI and calls the processor. Checkout loads it based on your Payment Integration configuration; it can also be embedded directly in a custom frontend.

The rule to internalize first: never ship a gift card integration alone. A gift card Payment Integration must always be configured alongside at least one other Payment Integration (docs). A gift card often can't cover the full cart total; without a fallback method the shopper is stuck when the balance falls short. This is a configuration requirement, not a nice-to-have.

Gift card connectors are consumed by Checkout

Workflow

Step 0 — Gather context (required, run first)

node scripts/docs-search.mjs \
  --query "<gift card terms from the user's request, e.g. 'gift card connector checkout balance redeem payment method'>" \
  --app-name "<current-app ex: claude, copilot, codex>" \
  --model "<current-model>" \
  --skill-name "commercetools-integrations" \
  --limit 10

Step 1 — Extract requirements (before any config or code)

Gift card behavior is downstream of business facts, and the wrong default silently produces a broken checkout. Extract these first; each maps to a config key in Step 2 or a rung in Step 1.5. Ask the user (don't assume):

1. Which gift card system, and why? A dedicated gift-card/loyalty platform (e.g. Voucherify), an in-house ledger, or a store-credit service. Do they already have an account + API credentials?
2. Is there a public connector for it? Voucherify has one; most systems don't. This decides configure-vs-build (Step 1.5) and changes the effort estimate — say it early.
3. Region and project? e.g. europe-west1.gcp, project my-project — the CT API/Auth/Session hosts and JWKS/issuer config are region-specific.
4. Which fallback payment method(s)? The gift card integration is configured alongside another Payment Integration (PSP). Which one, and is it already deployed? (Non-negotiable — see the rule above.)
5. Currency handling? A single connector deployment is typically scoped to one currency; a multi-currency storefront may need multiple deployments or a system that handles conversion. Confirm the currencies in scope.
6. Partial + multiple cards? Should one cart accept multiple gift cards, and combine a card with a PSP payment for the remainder? (Usually yes — confirm the system supports partial redemption.)
7. Post-order operations? On cancellation/return, should redeemed value be refunded/reversed back to the card? → drives whether you implement the Payment Intents refundPayment/reversePayment operations, not just balance+redeem.
8. Anything special or non-standard? (always ask — open-ended) Expiry rules, per-transaction caps, PIN/security-code entry, fraud checks, combining with discount codes, B2B store credit, or a specific gift-card account/program id. Capture each as its own requirement line; don't force it into a slot above.

Step 1.5 — Use a public connector, customize one, or build a new one? (decide before wiring or building)

1. Use a public connector directly → if a Public Connector of type Gift Cards covers the system (e.g. Voucherify) or you just need a proof of concept (the sample gift card connector — see below), install + configure it (Step 2). Don't build.
2. Public connector, gap looks like a capability → prove it isn't config first. Many "missing" behaviors (currency, which operations are enabled, fallback pairing) are connect.yaml values or Merchant Center Payment Integration settings → back to rung 1.
3. Customize/fork a connector's code → genuine gap config can't close and an open-source connector exists for the system → fork it, add only the delta, deploy as an Organization connector. Don't rebuild a working one.
4. Build a new one from the template → no connector for the system → build from the gift card integration template. The template ships both apps with the Connect + session/JWT plumbing done; you implement the calls to your gift card service and the mapping. This is the common case.

Step 2 — Derive the config from the requirements

• The commercetools connection block (CTP_PROJECT_KEY, CTP_AUTH_URL, CTP_API_URL, CTP_SESSION_URL, CTP_JWKS_URL, CTP_JWT_ISSUER) — region-specific; the session/JWKS/issuer values are what let the processor validate Checkout sessions and Merchant Center JWTs.
• Currency config (one deployment ≈ one currency for the template/Voucherify) and the gift-card-system credentials.
• Secured vs standard config — the gift card system API secret and the CT client secret are securedConfiguration; URLs, currency, and behavioral toggles are standardConfiguration.
• The API-client scopes the connector needs (manage_payments, manage_orders, view_sessions, view_api_clients, manage_checkout_payment_intents, introspect_oauth_tokens).

Step 3 — Build/verify the two apps (the main body of work), test-first

1. Processor — balance + redeem (session-authenticated): POST /balance ({ code }) checks the gift card system and reports the balance and whether it covers the cart; POST /redeem ({ code, redeemAmount }) redeems value against the system and records it on the commercetools Payment. Handle insufficient balance (partial redemption, remainder to the fallback method) and zero balance.
2. Processor — post-order operations (POST /payment-intents/:id, JWT/OAuth, manage_checkout_payment_intents): implement modifyPayment for the operations in scope (refund, reverse/rollback). Driven by the Payment Intents API, not by the enabler.
3. Enabler — the frontend touchpoint that renders the gift-card input and calls the processor with the session. Thin slice; contract is in giftcard-contract.md.

Step 4 — Verify the round trip

References

Adding another gift card system later means adding a sibling provider note and extending the selection table — the two-app architecture, the contract, and the flow do not change.

Checklist

Requirements

• Gift card system chosen + account/credentials; region + project
• Fallback Payment Integration identified (gift card is never shipped alone); currency scope confirmed
• Partial + multiple cards decided; post-order refund/reverse decided
• Asked the open-ended "anything special?" question; each special requirement its own line
• Requirements block written and confirmed; specials fed into the Step 1.5 fit-check

Use / customize / build (decide before wiring/building)

• Checked live marketplace + gift-card docs (not memory); named the connector + version
• Ladder rung presented to the user and chosen by them: use public (1) · config-closes-gap (2) · fork/customize (3) · build from template (4)
• For a real gap on a system with a public connector, chose fork over rebuild
• Used the sample connector only for PoC, not production

Config (the deliverable)

• Only documented connect.yaml envelope fields; file at the repo root
• CT connection block + JWKS/issuer set for the region; currency configured
• Scopes = manage_payments, manage_orders, view_sessions, view_api_clients, manage_checkout_payment_intents, introspect_oauth_tokens
• Gift-card-system secret + CT client secret in securedConfiguration; URLs/currency in standardConfiguration

The two apps (build test-first — do not write a function body before its red test)

• /balance and /redeem session-authenticated; redeem creates/updates the Payment idempotently
• Partial redemption leaves a remainder for the fallback method; zero balance handled
• /payment-intents/:id refund/reverse implemented (if in scope), JWT/OAuth-authenticated
• Boundary mocked; suite runs with no deployment/secrets

Verification

• Balance check returns the correct amount; redeem creates a Payment transaction
• Remainder covered by the fallback method; refund/reverse returns value (if in scope)
• Understood: the sample connector only simulates; a gift card shown with no fallback is a config error, not a bug

Verify the gift card round trip

Check 1 — balance reads correctly (and doesn't redeem)

• The response reports the correct balance and whether it covers the cart. In Checkout this surfaces as the gift_card_balance_success Message with amount and isBalanceSufficient.
• The balance did not change from checking it. A balance call that redeems or reserves value is a bug — check again and confirm the amount is unchanged.

Check 2 — redeem records a Payment transaction, remainder to fallback

• A commercetools Payment exists with a transaction for the redeemed amount (gift_card_redeem_success in Checkout).
• If the balance was less than the cart total, the outstanding amount is left for the fallback Payment Integration (the PSP), and completing the order requires paying that remainder. A short balance should never block checkout — it should route the rest to the fallback method.
• Multiple cards, if used, each add their own transaction.

Check 3 — refund / reverse (if in scope)

• A refund returns value to the card and records a refund transaction on the Payment.
• A reverse/rollback unwinds a redemption; automated reversals require the connector to support reversePayment.

The two traps (correct behavior that looks like a bug)

Trap 1 — the sample connector only simulates

Trap 2 — a gift card shown with no fallback looks broken

Verification checklist

• Balance check returns the correct amount and does not change the balance
• Redeem records a transaction on a commercetools Payment
• Short balance leaves a remainder covered by the fallback PSP integration (checkout not blocked)
• Multiple cards each record a transaction (if in scope)
• Refund/reverse via the Payment Intents API returns/unwinds value (if in scope)
• Understood: the sample connector only simulates — verify real redemption against the real connector
• Understood: a gift card with no fallback method is a config error, not a connector bug

Requirements → seller model → marketplace connector config

Model the marketplace domain onto commercetools

commercetools has no "seller" resource. Sellers are modeled with Channels, Stores, and Custom Objects — pick per requirement, not all of them by default.

Two limits that kill naive designs

• 50 Subscriptions and 25 Extensions per Project. Never one per seller. Register one Subscription per message type and fan out to sellers inside your handler.
• Store-scoped connectors don't scale per-seller either. The product-export template deploys one Deployment per Store; with many sellers, one Deployment per seller is an operational trap — build a single app that resolves the seller from the resource instead.

Role + direction → app composition

• service inbound webhook — the marketplace pushes seller/offer/inventory/price changes; you authenticate the caller and upsert. 5-min service timeout applies (not the extension limit).
• job poll — when the marketplace can't push, or for large periodic feeds.
• event app on OrderCreated — group the Order's lines by seller (their supply channel) and push each group to the marketplace; record syncInfo.
• event app on order/state changes — fulfilment, cancellation, and return status both ways.
• job reconciliation — full sweep for drift (missed offers, stock divergence, orders the event path dropped), checkpointed.

• event app on Product/Product Selection/Store/price/inventory messages — export listing, price, and stock deltas (the product-export template is the closest starting shape).
• job — full/batch feed export when the marketplace wants scheduled files instead of deltas.
• service webhook or job — import marketplace orders (Order Import, keyed on orderNumber).
• event app — push shipment/tracking/cancellation back to the marketplace.

The connect.yaml envelope

Native client provisioning (prefer this)

inheritAs:
  apiClient:
    scopes:
      # operator, inbound seller + offer sync
      - manage_products               # Products/Variants — and Channels + Inventory Entries
      - manage_standalone_prices      # only if seller offers are Standalone Prices
      - manage_key_value_documents    # only if seller profiles are Custom Objects
      - manage_orders                 # Order Import (seller role) / updateSyncInfo (operator)
      - manage_types                  # only if postDeploy creates Custom Types
      # plus, per app, the narrowest of:
      # - view_products / view_orders  (read-only apps)
      # - manage_stores, manage_product_selections  (only with Store-per-seller)
      # - manage_subscriptions         (apps whose postDeploy registers Subscriptions)
  configuration:
    standardConfiguration:
      - key: MARKETPLACE_BASE_URL
        description: Marketplace API base URL (sandbox vs production)
      - key: SELLER_CHANNEL_KEY_PREFIX
        description: Prefix for seller Channel keys, e.g. "seller-"
    securedConfiguration:
      - key: MARKETPLACE_API_TOKEN
        description: Marketplace API token / OAuth client secret
      - key: MARKETPLACE_WEBHOOK_SECRET
        description: Shared secret or signing key used to authenticate inbound webhooks

Scope notes. manage_products covers Channels and Inventory Entries too — there is no separate channel or inventory scope, so seller Channels and per-seller stock need no extra grant. Standalone Prices, Stores, Product Selections, and Custom Objects each need their own scope (manage_standalone_prices, manage_stores, manage_product_selections, manage_key_value_documents) — a frequent cause of a working-locally-but-403-in-Connect connector. Check the current list in API scopes rather than guessing, and grant per app, not per connector. view_subscriptions is not a valid standalone scope; manage_subscriptions covers read + write. Give manage_orders only to the app that writes orders.

Per-app config

deployAs:
  - name: seller-offer-sync            # operator: marketplace pushes sellers + offers
    applicationType: service
    endpoint: /sellerOfferSync         # the Express router must mount at this same base path
    scripts:
      postDeploy: npm ci --omit=dev && npm run connector:post-deploy
      preUndeploy: npm ci --omit=dev && npm run connector:pre-undeploy
  - name: order-router                 # operator: route each seller's lines out
    applicationType: event
    endpoint: /orderRouter
    scripts:
      postDeploy: npm ci --omit=dev && npm run connector:post-deploy   # registers the OrderCreated Subscription
      preUndeploy: npm ci --omit=dev && npm run connector:pre-undeploy
    configuration:
      standardConfiguration:
        - key: CONNECT_SUBSCRIPTION_DESTINATION
          description: "GoogleCloudPubSub or SNS"
  - name: marketplace-reconcile        # drift sweep
    applicationType: job
    endpoint: /marketplaceReconcile
    properties:
      schedule: "0 3 * * *"

Worked example (operator, Marketplacer-style service, build/fork)

inheritAs:
  apiClient:
    scopes:
      [
        manage_products, # Products/Variants + seller Channels + Inventory Entries
        manage_standalone_prices, # per-seller offer prices
        manage_key_value_documents, # seller profile Custom Objects
        manage_orders, # updateSyncInfo on routed Orders
        manage_subscriptions, # postDeploy registers the OrderCreated Subscription
        manage_types, # postDeploy creates the line-item Custom Type
      ]
  configuration:
    standardConfiguration:
      - key: MARKETPLACE_BASE_URL
        description: "Marketplace API base (sandbox vs prod)"
    securedConfiguration:
      - key: MARKETPLACE_API_TOKEN
        description: Marketplace API token
      - key: MARKETPLACE_WEBHOOK_SECRET
        description: Signing secret for inbound webhooks
deployAs:
  - name: seller-offer-sync
    applicationType: service
    endpoint: /sellerOfferSync
    scripts: { postDeploy: "npm ci --omit=dev && npm run connector:post-deploy", preUndeploy: "npm ci --omit=dev && npm run connector:pre-undeploy" }
  - name: order-router
    applicationType: event
    endpoint: /orderRouter
    scripts: { postDeploy: "npm ci --omit=dev && npm run connector:post-deploy", preUndeploy: "npm ci --omit=dev && npm run connector:pre-undeploy" }
  - name: marketplace-reconcile
    applicationType: job
    endpoint: /marketplaceReconcile

Which path: use as-is, customise, or build?

Check live data first — don't answer from memory

The marketplace changes. Before recommending anything:

1. Browse the live Marketplaces category and the connector list; run this skill's docs-search script / the Knowledge MCP for the service name.
2. For each candidate, capture: name, vendor, is it a Connect connector, direction, and what it syncs (sellers / offers / inventory / prices / orders / shipments).
3. Name the connector and version you checked — or record that none exists — in the requirements block. Don't quote a listing's badge wording as a capability; badges describe the listing relationship, not what the code does.

The marketplace landscape (verify live — this is only the shape)

Two structural facts shape almost every marketplace engagement:

• Most marketplace listings are partner integrations, not Connect connectors. A vendor-operated integration, an iPaaS pipeline, or a cloud-function accelerator can be an excellent functional match and still have nothing Connect can deploy.
• There is no marketplace Connect template. The templates are payment-integration, product-export, tax-integration, and transactional-emails. A build therefore starts from plain apps — though for the seller role (pushing your catalog out to a marketplace) the product-export template is a genuinely close starting shape: it already does Store-scoped full export plus an incremental updater driven by Product/Product Selection/Store messages.

Verify it's an actual Connect connector — then ask the user

Marketplace-specific checks before treating any listing as path 1 or 2:

• Look for a connector repo with a root connect.yaml and deployAs apps. No connect.yaml, no Connect deployment.
• A "connector" that deploys as the vendor's own cloud function, iPaaS flow, or hosted service is not a Connect application, whatever the listing or repo name says — a common shape for marketplace accelerators specifically.
• The marketplace platform's own commercetools integration may be operated by the platform, with nothing for you to deploy at all; that's a vendor onboarding task, not a connector build.

Present the three paths and let the user choose

Show the live findings, then ask. Don't skip straight to building.

Path 1 — Use a public connector directly (configure, no code)

Path 2 — Customise it (fork an open-source connector)

Assess the candidate before you fork — from the repo, not from memory

1. connect.yaml at the repo root — the deployAs apps and their applicationType tell you which directions it covers (inbound service, outbound event, batch job) and therefore which of the user's requirements it can't meet at all. Also read whether it uses inheritAs.apiClient.scopes or hand-supplies CTP_CLIENT_ID/CTP_CLIENT_SECRET, and what its config keys are.
2. The handler entry points — how it identifies resources (upsert by key vs blind create), whether it authenticates inbound callers, and whether it re-fetches by id.
3. The mapping code — what it maps sellers and offers onto, which is what you'll be rewriting per config-from-requirements.md.
4. Language and framework — Java/Spring and TS/Node connectors both exist. Don't port; the commercetools-connect skill's contracts are language-agnostic, and a rewrite discards the mapping you forked for.
5. README and repo framing — many marketplace connectors are published as accelerators or reference implementations, documented in the same spirit as the Connect templates: starting points that require customization before production use. Tell the user which grade they're forking.

• the commercetools-connect skill's production-readiness checklist — inbound authentication, native client provisioning, secrets in securedConfiguration, no stack traces in responses, idempotent lifecycle scripts, structured logs, health endpoint, tests that assert behavior, README;
• this sub-area's contract and pitfall catalog — upsert by marketplace id, seller Channel actually created, offers linked to a seller, one Product for a shared SKU, channel on every seller price, supply channel on every InventoryEntry, integer minor-unit money conversion, no hardcoded currency/locale/region, delisting handled, syncInfo before order export, and the directions the original omits.

Known landmarks (verify live — these change)

Pointers so you know a fork is even possible, not a substitute for reading the repo:

• Marketplacer has publicly available, open-source Connect connector code under the commercetools GitHub organization — inbound seller/listing sync, Java/Spring, published as an accelerator. It's the concrete path-2 candidate today.
• A separately branded Marketplacer accelerator also exists that deploys as a cloud function, not a Connect application — the listing-is-not-a-connector trap in its purest form.
• Mirakl appears in the category through vendor and partner listings; check live whether any is Connect-deployable before assuming path 1 or 2.

Path 3 — Build a new connector for the marketplace service they define

• Operator: inbound seller sync + inbound offer/inventory/price sync (service webhook and/or job poll), outbound order routing (event on OrderCreated), fulfilment status sync, reconciliation job.
• Seller role: outbound catalog/price/stock export (event, or job for batch feeds), inbound marketplace order import (service webhook or job), outbound shipment/tracking.

The ladder (stop at the first rung that fits)

1. Is the listing a deployable Connect connector at all? If not → outside this skill: surface it with the not-a-Connect-solution warning, then offer forking an open-source alternative or building.
2. Connect-deployable connector covers the requirements → install + configure (path 1).
3. Right service, gap looks like a capability → prove it isn't config/mapping first → back to rung 1.
4. Right service, genuine gap config can't close, and it's open source → fork (path 2). Don't rebuild a working sync engine.
5. No usable connector for the service → build (path 3). No marketplace template; product-export is the closest shape for outbound.

Only rungs 3–4 leave this sub-area (hand off to the commercetools-connect skill for build/publish); the flow resumes here once the connector is deployed.

Recording the decision

Marketplacer · operator role · path 2 (fork) · checked the Marketplaces category and the open-source Marketplacer connector repo — Connect-deployable (root connect.yaml, two service apps) but inbound catalog/seller only, accelerator-grade · forking to add order routing, native client provisioning, webhook auth, and idempotent seller upserts (backlog scored against the production gate + contract).

Checklist

• Checked the live Marketplaces category + connector list (not memory); cited each candidate + version
• Verified Connect-deployability per candidate (root connect.yaml / CLI registry — not the listing page)
• A good-match listing that isn't a Connect connector was surfaced with the not-a-Connect-solution warning, not treated as path 1
• Presented all three paths to the user (use as-is · customise/fork · build for their service) and let them choose
• Apparent gaps re-checked as config/mapping before proposing code
• Fork chosen over from-scratch whenever an open-source connector for the service exists
• Told the user there is no marketplace template (and that product-export is the closest shape for outbound)
• Decision + rung + version recorded in the requirements block

The marketplace sync contract

The rule that spans every app: upsert by the marketplace's id, never blind-create

App 1 — seller sync (inbound, service webhook or job poll)

• Authenticate the caller. The marketplace calls you, so validate its proof — signature, shared secret, or JWT — before any write (security.md). An unauthenticated seller endpoint lets anyone create Channels and Products in the Project. (AuthorizationHeader authentication on an Extension's HTTP destination is the reverse mechanism, for commercetools calling your endpoint; it does not authenticate inbound marketplace traffic.)
• Upsert the seller Channel by key, with the roles the model requires (InventorySupply, and ProductDistribution when the seller prices independently). Store the profile payload in a CustomObject and/or Channel Custom Fields.
• Only create a Store per seller if isolation was a requirement — and remember a Store is capped at 100 Product Selections.
• Offboard by deactivating, not deleting. Remove the Channel from Stores, deactivate the seller's Product Selection / delist their offers, and stop syncing. A Channel cannot be deleted while it is referenced by an InventoryEntry, LineItem, Store, Price, StandalonePrice, or CartDiscountValueGiftLineItem — the documented order is Carts → Orders → Stores → Channel. Note StandalonePrice is on that list and is the offer-price model recommended above, so a seller synced that way is blocked by their own prices, not just by orders. Deleting a departed seller's historical Orders to satisfy that is technically the documented path, but it destroys order history; deactivation is the right offboarding move.
• Idempotent — the same seller webhook twice must be a no-op.

App 2 — offer / inventory / price sync

Inbound (operator): marketplace → commercetools

• Upsert the Product by listing key; when several sellers sell the same SKU, resolve to the one shared Product and add the seller's price and stock, not a second Product.
• Every price carries the seller's distribution channel. A channel-less price is visible in every Store — the cross-seller price leak.
• Every InventoryEntry carries the seller's supply channel (sku + supplyChannel). Writing stock without a channel makes it global stock for all sellers.
• Map deliberately. Localized names/descriptions, currency, and money precision are where feeds go wrong: build the LocalizedString from the marketplace's locale rather than hardcoding one, derive the currency per seller/country rather than hardcoding it, and convert to centAmount in integer minor units — multiply then round, never cast a float first (a (long) price * 100 style conversion silently drops the cents). High-precision cases: money types.
• Keep the mapping a pure function — no network calls — so it is unit-testable without a deployment or token.
• Don't publish blind. Decide whether an imported offer is published immediately or staged for review, and make it explicit in config.
• Bulk belongs in the Import API. Initial and periodic full loads go through the Import API (asynchronous, dependency-resolving, keyed → idempotent); the webhook path handles deltas. Keep them separate apps.

Outbound (seller role): commercetools → marketplace

• Driven by Subscription messages on products, prices, inventory, Product Selections, and Stores — the product-export template is the closest existing shape (full export endpoint + incremental updater).
• Re-fetch the resource by id from resource.id; don't map from a possibly-stale or truncated payload. With no ordering guarantee, re-fetching makes the export converge on current state instead of replaying old deltas.
• Scope what you export — which Store / Product Selection / channel defines "listed on this marketplace". Exporting the whole catalog to a marketplace that only sells a subset is a compliance and delisting problem.
• Delist explicitly. Unpublish, removal from a Product Selection, and stock hitting zero each need a defined outbound action; otherwise you keep selling items you no longer carry.
• Respect the marketplace's feed contract — batch sizes, schedules, and rate limits. Retry 429/5xx with exponential backoff.

App 3 — orders

Inbound (seller role): import a marketplace order

• Dedupe on orderNumber = the marketplace order id: query first, import only if absent. Order has no top-level externalId, so orderNumber (or a Custom Field) is the link.
• Use Order Import — it creates an Order without a Cart. Set store, per-line supplyChannel/distributionChannel, and per-line custom fields for the marketplace line id. Note totalPrice must be set explicitly (it is not derived from the line items) and negative prices/quantities are not rejected — validate the payload yourself.
• Record the inbound sync with updateSyncInfo against a Channel with role OrderImport.
• Decide the inventory mode deliberately: stock was already committed on the marketplace side, so double-decrementing local stock is a real risk.

Outbound (operator): route lines to sellers

• Triggered by an OrderCreated MessageSubscription (registered idempotently in postDeploy — get-then-create, never delete-then-recreate).
• Decode the envelope before use: the GCP transport wrapper is { "message": { "data": "<base64>" } }, and the message body is PlatformFormat or CloudEventsFormat depending on config. Validate the type, then ack-and-ignore anything you don't handle (including the platform's test messages).
• Re-fetch the Order by id, then group Line Items by seller (their supplyChannel, or the seller reference you set at add-to-cart). Push one payload per seller — a multi-seller order is N seller orders downstream.
• Record updateSyncInfo per seller Channel (role OrderExport) with the marketplace's id and syncedAt, and read syncInfo first so a redelivered message doesn't double-submit. That's your idempotency mechanism; combine it with the marketplace's own idempotency key if it has one.
• Ack correctly — 2xx (the event contract treats 102/200/201/202/204 as "don't redeliver") for handled and deliberately-ignored messages; non-2xx only for transient failures you want redelivered.
• Partial failure is normal. If seller A's push succeeds and seller B's fails, don't re-push A on retry — per-seller syncInfo makes the retry converge instead of duplicating.

App 4 — fulfilment, cancellation, and return status

• One Order, many sellers → track per line, not per order. Use Line Item state (ItemStates) transitions for per-seller progress, and Deliveries/Parcels for split shipments; an order-level shipmentState alone can't express "seller A shipped, seller B cancelled".
• Tracking numbers, carrier, and shipment events flow back per seller shipment; cancellations and returns must map to the marketplace's own state machine, not just a local status field.
• Self-change filtering wherever a domain syncs both ways: a status you write inbound raises a message your outbound app would push straight back. Mark connector-originated writes (a syncSource Custom Field, or compare against syncInfo) and skip them. One-way per domain avoids this entirely.

App 5 — reconciliation job

Pitfall catalog

Test-first checklist (mirror in the suite)

Seller sync

• Rejects unauthenticated / bad-signature calls (parameterized auth matrix)
• Upserts the Channel by key; second delivery is a no-op
• Roles and profile storage asserted; offboarding deactivates rather than deletes

Offer / inventory / price sync

• Same-SKU second seller adds a price + inventory entry, does not create a second Product
• Every written price has a channel; every InventoryEntry has a supply channel
• Money conversion asserted on a value with non-zero cents; locale/currency taken from input
• Delist path asserted (unpublish / removed from selection / zero stock)
• Outbound: re-fetches by id, exports only in-scope products

Orders

• Inbound: duplicate marketplace order id imports once; totalPrice set; syncInfo recorded
• Outbound: multi-seller order produces one payload per seller with only that seller's lines
• Redelivered OrderCreated pushes nothing (syncInfo short-circuit)
• Partial failure retries only the failed seller
• Envelope/ack matrix covered

Fulfilment + reconciliation

• Per-line state transitions asserted; split shipment maps per seller
• Self-change filter asserted on any two-way domain
• Reconciliation resumes from checkpoint after a simulated failure; repairs are upserts
• Boundary mocked; suite runs with no deployment and no secrets

Marketplace connector — integrate a marketplace service

First, disambiguate the word "marketplace" — ask if it isn't obvious. Two unrelated meanings collide here:

• The commercetools Connect marketplace — marketplace.commercetools.com, the catalog where connectors and integrations are listed. Every connector task touches this.
• A marketplace business model — selling third-party sellers' assortments, or selling your assortment on someone else's marketplace. That is what this sub-area is about.

"Build a marketplace connector" almost always means the second. If the user actually meant "publish my connector on the Connect marketplace", that's the commercetools-connect skill's deployment-installation.md, not this file.

Step 1 — Fix the role, then the direction

Everything else follows from these two answers. Get them before proposing an architecture.

Workflow

Step 0 — Gather context (required, run first)

node scripts/docs-search.mjs \
  --query "<marketplace terms from the request, e.g. 'marketplace seller supply channel distribution channel store product selection order import syncInfo'>" \
  --app-name "<current-app ex: claude, copilot, codex>" \
  --model "<current-model>" \
  --skill-name "commercetools-integrations" \
  --limit 10

Step 1 — Extract requirements (before any config or code)

Ask the user — don't assume:

1. Which marketplace service, and what API access? Marketplacer, Mirakl, Convictional, a channel manager, an operator's own portal, or a service they define. Webhooks vs polling, credentials, sandbox, rate limits.
2. Role and direction (the table above). Operator, seller, or both.
3. Source of truth per domain — offer content, inventory, price, order, seller record.
4. How many sellers, and do they need isolation? Isolated storefront/catalog/permissions per seller → Store-per-seller; a shared catalog with per-seller offers → Channel-per-seller only. Drives Step 2.
5. Do multiple sellers sell the same SKU? If yes, one Product with per-seller prices and stock — not one Product per seller. This is the single most consequential modeling answer.
6. Which entities sync? Sellers, offers/listings, inventory, prices, orders, shipments/tracking, returns/cancellations, invoices.
7. Order flow. Does commercetools capture the order and route lines to sellers (operator), or does the marketplace capture it and you import it (seller)? Can one cart span sellers → split shipments and per-line fulfilment states?
8. Commission, payout, and settlement. Confirm explicitly that these stay in the marketplace/PSP: commercetools only tracks Payment status and has no payout ledger. Don't model seller payouts as commercetools resources.
9. Seller onboarding/offboarding. Approval flow, and what happens on offboarding — note up front that a Channel can't be deleted while it's referenced by inventory, a Line Item, a Store, or a Price, so offboarding is deactivation, not deletion.
10. Anything special or non-standard? (always ask — open-ended) Seller-specific shipping rules or lead times, per-seller tax, drop-ship vs consignment, marketplace-imposed feed formats/schedules, returns arbitration, multi-currency or multi-country sellers, seller-facing UI in the Merchant Center. Capture each as its own requirement line; don't force it into a slot above.

Step 1.5 — Ask the user which path: use as-is, customise, or build

1. Use a public connector directly — install and configure it, no code. Only valid if the listing is an actually deployable Connect connector.
2. Customise it — fork an open-source connector and add only the delta (the realistic path for marketplace work). Assess the candidate by reading its current repo — connect.yaml, handlers, mapping — and score it against the production gate and this sub-area's contract; don't work from a remembered gap list.
3. Build a new one for the marketplace service they define — no listing fits, or the service is bespoke. There is no marketplace Connect template, so you scaffold plain service/event/job apps.

Record the chosen path, the connector name + version you checked (or "none exists"), and why, in the requirements block.

Step 2 — Model sellers and offers, then derive the config

Step 3 — Price the async contract (reference)

Step 4 — Build/verify the sync apps (the main body of work), test-first

1. Seller sync (inbound) — upsert a Channel (and Store/CustomObject) per seller, keyed on the marketplace seller id.
2. Offer/listing sync — inbound (operator): upsert Products/prices/inventory per seller; outbound (seller role): export catalog/price/stock changes to the marketplace.
3. Order app — inbound (seller role): import marketplace orders via Order Import keyed on orderNumber; outbound (operator): route each seller's lines on OrderCreated and record the hand-off in the Order's syncInfo.
4. Fulfilment/status app — shipment, tracking, cancellation and return states back to the other side, per line/per seller.
5. Reconciliation job — periodic full sweep that catches what events dropped (offers, stock drift, missed orders), checkpointed.

Step 5 — Verify the round trip

References

Adding another marketplace service later reuses this tree unchanged — the role/direction split, the seller model, and the keying rules don't change; only the service's API and payloads do.

Checklist

Requirements

• "Marketplace" disambiguated (business model vs the Connect marketplace listing catalog)
• Role fixed (operator / seller / both) and direction per domain decided
• Source of truth named per domain (offer, inventory, price, order, seller)
• Seller count and isolation needs known; same-SKU-multiple-sellers answered
• Entities in scope listed; order flow (route vs import) decided
• Commission/payout confirmed as out of scope for commercetools
• Offboarding path decided (deactivate, not delete — Channel delete constraints)
• Asked the open-ended "anything special?" question; each special requirement its own line
• Requirements block written and confirmed

Path (asked, not assumed)

• Checked live marketplace listings; named connector + version (or "none exists")
• Verified any candidate is a deployable Connect connector, not a partner/SaaS listing
• Presented all three paths — use as-is · customise/fork · build for their service — and let the user choose
• Chosen path + rung recorded

Modeling and config

• Seller modeling decided (Channel per seller; Store/Product Selection only if isolation is needed; CustomObject for profile data)
• Offer keying decided; same-SKU sellers modeled as one Product with per-seller prices/stock
• Every seller price carries a distribution channel; every InventoryEntry a supply channel
• inheritAs.apiClient.scopes least-privilege; marketplace credentials in securedConfiguration
• No per-seller Subscriptions or Extensions (Project limits)

The sync apps (build test-first)

• Every write is an upsert keyed on a stable marketplace id
• Inbound orders deduped on orderNumber; outbound hand-off recorded in syncInfo
• Per-seller fulfilment tracked per line item, not per order
• Reconciliation job checkpointed; rate limits respected (batch + backoff)
• Boundary mocked; suite runs with no deployment/secrets

Verification

• Seller, offer, and order round trips proven; multi-seller order splits correctly
• Re-delivery of the same webhook/message creates no duplicate

Verify the marketplace round trip

Check 1 — the seller exists and is usable, not just present

Create or change a seller on the marketplace side, then confirm:

• The seller Channel exists with the expected key (seller-<marketplaceSellerId>) and the roles the model needs (InventorySupply, ProductDistribution where the seller prices independently).
• Profile data landed where the model says (CustomObject / Channel Custom Fields).
• If Store-per-seller is in scope: the Store exists, references that Channel, and its Product Selection is assigned.
• Re-send the same seller webhook: nothing duplicates and no version conflict is raised.

A seller that exists only as a CustomObject with no Channel is the tell that the model is incomplete — stock and price have nothing to scope to.

Check 2 — the offer is sellable, per seller

Create or update a listing, then confirm end to end (not just "the Product appeared"):

• The Product/Variant exists, keyed on the marketplace listing id, published according to the configured publish/staging decision.
• A Price carrying the seller's distribution channel exists — and the amount is exact, cents included (this is where float→cent bugs surface).
• An InventoryEntry for sku + the seller's supply channel exists with the expected quantity.
• Add it to a Cart in the seller's context (Store-bound if Store-per-seller, otherwise with the seller's channels on the Line Item) and confirm the correct price and availability are selected. A Product that exists but can't be added at the seller's price is not a working offer.
• Second seller, same SKU: sync a second seller's offer for the same SKU and confirm no second Product is created — only an additional price and inventory entry.
• Delist: unpublish / remove from the selection / drop stock to zero on the marketplace side and confirm it stops being sellable.

Check 3 — the order flows once

• Each seller received one payload containing only their own lines — with correct quantities and prices.
• The Order carries a syncInfo entry per seller Channel with the marketplace's externalId.
• Redeliver the OrderCreated message: nothing is pushed again (the syncInfo short-circuit works). This is the single most valuable assertion in the suite.
• Force one seller's push to fail: on retry, only the failed seller is re-pushed.

Check 4 — fulfilment splits per seller

The traps (behavior that looks like a bug — or hides one)

Trap 1 — the channel-less price leak

Trap 2 — availability looks wrong because it's aggregated

Trap 3 — "sync stopped" is usually throttling

Trap 4 — sandbox marketplaces don't behave like production

Trap 5 — the seller you can't remove

Verification checklist

• Seller Channel (and Store, if modeled) created with the right key and roles; re-delivery is a no-op
• Offer sellable: price with channel and exact amount, InventoryEntry with supply channel, add-to-cart proven in the seller's context
• Second seller of the same SKU adds price + stock, no duplicate Product
• Delist path proven
• Inbound order: one Order per marketplace order id, totalPrice correct, syncInfo recorded, redelivery creates nothing
• Outbound order: one payload per seller with only their lines, syncInfo per seller channel, redelivery pushes nothing, partial failure retries only the failed seller
• Fulfilment states tracked per line; split shipment and mixed ship/cancel proven
• Reconciliation job resumes from checkpoint; backoff verified under throttling
• No secrets or payload dumps in logs; error responses carry no stack traces
• Test sellers/listings/orders cleaned up on both sides

Build a new OMS connector

Start from the fulfilment-integration template

commercetools connect init my-oms-connector --template fulfilment-integration

Connecting to the user-defined OMS

The OMS is an arbitrary external system — treat its API as the untrusted outbound/inbound boundary:

• Config, not code. OMS base URL, tenant/account id, and non-secret toggles → standardConfiguration. OMS API key/client secret, webhook signing secret → securedConfiguration, never hardcoded (security.md).
• Deploy-time validation. postDeploy should test-connect to the OMS and surface bad credentials immediately, and register the Subscription + any custom State machine / Custom Types idempotently (get-then-create, never blind delete-recreate) → lifecycle-scripts.md.
• Map at the boundary. Convert between the OMS's order/status model and commercetools' at the edge; keep SDK types end to end internally, no any escapes (project-structure.md). The concrete field/action mapping is sync-architecture.md.
• Least-privilege scopes. inheritAs.apiClient.scopes with only what the flows need — typically manage_orders, view_orders, manage_subscriptions, and manage_inventory if syncing stock — not manage_project.
• Fail-open vs fail-closed. Since the export is async and the inbound is a webhook (neither on a synchronous checkout path), a transient OMS outage should fail closed with retry (return non-ack / non-2xx to trigger redelivery), not silently drop. Document the stance in the README.

Build test-first, then deploy

Checklist

• Scaffolded from the fulfilment-integration template (connect init --template fulfilment-integration); kept only the needed apps (order-export/order-updates/inventory-import), added a reconcile job if required
• Applications declared in a root connect.yaml using only documented envelope keys; router mounts match endpoint; order-export is deployAs: event
• OMS URL/tenant in standardConfiguration; OMS + webhook secrets in securedConfiguration
• postDeploy validates OMS connectivity and idempotently registers Subscription + custom States/Types; preUndeploy cleans up
• Least-privilege scopes (manage_orders / view_orders / manage_subscriptions / manage_inventory as needed)
• Fail-open/closed stance documented; inbound webhook authenticated
• Built test-first; sync invariants pinned as tests; deployed via connectorstaged → publish → deployment create

Is a public OMS connector enough?

Two things that are easy to get wrong

• Installable Connect connector — published to Connect, deployed into your project via the Connect CLI / UI. This is the "install + configure" case.
• Vendor-hosted / partner integration — the OMS vendor operates the integration on their side (their connector calls the commercetools API, or you configure it in the vendor's console). You don't deploy anything in Connect; setup follows the vendor's docs.

Discover public connectors programmatically — don't hardcode a list

GET {connect-host}/connectors/search?integrationTypes=oms
# add &integrationTypes=shipping for fulfillment/shipping connectors; &text=<keyword> to narrow

• Filter by the right type(s). IntegrationType values (verified against the Connect API): tax, marketplace, oms, psp, pim, promotion, search, erp, crm, email, analytics, shipping, giftcard. There is no separate fulfillment value — fulfillment/OMS connectors are tagged oms and/or shipping, so query both for an order-management use case. → schema: openApi-schemata.mjs --resource-name connect-Connector; host/auth: Connect hosts & authorization.
• Read the result. Each returned Connector carries name, key, integrationTypes, creator, repository, configurations, supportedRegions, certified, private, and documentationUrl. Use certified: true / private: false to identify public certified connectors; repository tells you whether the source is available to fork; configurations is the config surface you'd fill at install. Name the version you found.
• Equivalent surfaces: the same search is available in the Merchant Center (Connect) and the Connect CLI; the marketplace is the human-browse view (note connectors span both the order-management and fulfillment marketplace categories — the API oms+shipping query covers both).
• For a specific candidate, its repository/documentationUrl is authoritative for capabilities, install shape, and config keys.

Turn the search result into the decision

Run the search first, then branch on what it returns — this is how the ladder below is driven:

• A published connector matches the OMS and covers the flows → install it (rung 1) — deployment create with the connector's configurations.
• A published connector matches but a behavior is missing → try config first (rung 2); if genuinely missing and its repository is available → modify/fork it (rung 3).
• No published connector matches the OMS → build one (rung 4): from scratch or, preferably, the fulfilment-integration template → build-oms-connector.md.

State explicitly that you're checking current data, and cite the connector key + version you found.

The fit check

Compare the Step 1 requirements against what a candidate connector actually supports. Check each dimension: