commercetools Connect

Architecture Decisions

Table of Contents

• Pattern 1: Pick the application type
• Pattern 2: Price the synchronous contract (service as API Extension)
• Pattern 3: Price the asynchronous contract (event)
• Pattern 4: Combine application types in one connector
• Pattern 5: Is Connect the right fit? (best practices)
• Checklist

Pattern 1: Pick the application type

A service app is just an HTTP endpoint; API Extension is one mode, inbound webhook is another — see service-applications.md. Note that event apps consume commercetools' own Subscription messages only; an external system's changes never arrive as event messages, so "external → commercetools" is always service (reactive) or job (scheduled).

Pattern 2: Price the synchronous contract (service as API Extension)

• Latency is additive. Connection must establish within 1 s; the response limit is 2 s by default, configurable up to 10 s (timeoutInMs); beyond that needs a per-project review. Every millisecond your extension takes is added to the customer's cart/checkout call.
• Availability is coupled. If your extension fails or times out, the commercetools operation fails or stalls. It is applied to all clients, including the Merchant Center.
• Therefore you must decide: fail-open (let the operation proceed on error) or fail-closed (block it), and budget an outbound timeout well under the extension timeout.

Pattern 3: Price the asynchronous contract (event)

• At-least-once delivery. The same message may arrive more than once → you must be idempotent.
• No ordering guarantee. Messages can arrive out of order, especially after retries → never assume "created before updated"; use sequenceNumber (Message) or re-fetch current state.
• Redelivery on non-ack. If you don't acknowledge (Connect: any response other than 102/200/201/202/204), the message is retried. A bug that returns 500 on an unprocessable message becomes an infinite redelivery loop.
• No delivery-time guarantee. Usually seconds, but minutes are possible. Do not use Subscriptions for time-critical paths.

Pattern 4: Combine application types in one connector

deployAs:
  - name: tax-extension
    applicationType: service      # price the cart synchronously at checkout
    endpoint: /service
  - name: tax-committer
    applicationType: event        # commit/void the tax document after the order is placed
    endpoint: /event

Pattern 5: Is Connect the right fit? (best practices)

If a use case fails these, the answer may be "not a Connect app" — say so rather than forcing it.

Checklist

• Connector is stateless, single-responsibility, and fits the runtime timeouts (best practices)
• Each application's type chosen by invocation timing, not domain
• For every service API Extension: latency budget and fail-open/closed stance written down → service-applications.md
• For every service inbound webhook: caller auth and idempotent-upsert strategy written down → service-applications.md
• "External system → commercetools" routed to service (reactive) or job (scheduled), never event
• For every event app: idempotency key and redelivery-safe ack strategy written down → event-applications.md
• Work that doesn't need to block the operation is an event, not a service
• Shared code factored into a shared/ workspace, not duplicated per app

Connect CLI

Step 1. Install the CLI and authenticate

npm install -g @commercetools/cli
commercetools --version
commercetools auth login --client-credentials \
  --client-id <id> --client-secret <secret> --region <region> --project-key <key>

Step 2. Scaffold the connector

commercetools connect init my-connector            # add: --template <name> to start from a template

Add another application to an existing connector later:

commercetools connect application add --type service|event|job --language typescript|javascript|java

Match the route to the endpoint. The platform routes traffic to {connect-url}/{endpoint}. Mount your router at the same base path as the endpoint in connect.yaml (e.g. endpoint: /service ↔ app.use('/service', router)), or all traffic 404s.

Step 3. Pin dependency versions

These are the minimum supported versions for a connector built with this tooling. Pin them; do not fall back to older clients.

npm install \
  @commercetools/platform-sdk@^8 \
  @commercetools/ts-client@^4

• @commercetools/platform-sdk@^8 — the typed API builder (createApiBuilderFromCtpClient).
• @commercetools/ts-client@^4 — the client (ClientBuilder). Do not use the legacy @commercetools/sdk-client-v2.

<dependency>
  <groupId>com.commercetools.sdk</groupId>
  <artifactId>commercetools-sdk-java-api</artifactId>
  <version>19.0.0</version>    <!-- commercetools Java SDK 19 or above -->
</dependency>

• commercetools Java SDK 19+

Step 4. Develop and test locally

Run everything through the CLI so local behavior matches the platform:

commercetools connect application build     # build
commercetools connect application start     # run locally
commercetools connect application test      # run the test suite
commercetools connect validate              # validate connect.yaml + apps before shipping
commercetools connect bundle                # bundle the applications

Step 5. Stage, preview, publish, and deploy

# Register the staged (private) connector from your git repo:
commercetools connect connectorstaged create \
  --repository-url <url> --repository-tag <tag> --creator-email <email> --name <name>
commercetools connect connectorstaged describe --key <connector-key>
commercetools connect connectorstaged list

# Preview to test the staged connector (needs isPreviewable):
commercetools connect connectorstaged preview \
  --key <connector-key> --deployment-key <dep-key> --region <region>

# Publish so it can run in production:
commercetools connect connectorstaged publish --key <connector-key>
# Public marketplace listing only — certification:
commercetools connect connectorstaged certify --key <connector-key>

# Deploy / install into a project (this IS installation):
commercetools connect deployment create --connector-key <key> --region <region> --type preview|sandbox|production
commercetools connect deployment describe --key <deployment-key>
commercetools connect deployment logs --key <deployment-key> --application service --startDate <iso> --endDate <iso>
commercetools connect deployment redeploy --key <deployment-key> --configuration KEY=value
commercetools connect deployment list
commercetools connect deployment delete --key <deployment-key>

Flag names and exact options can evolve — confirm with commercetools connect <command> --help and the Connect CLI docs. Source of truth for platform behavior: docs.commercetools.com/connect.

Deployment & Installation

Table of Contents

• Pattern 1: The connect.yaml configuration contract
• Pattern 2: Deployment types and lifecycle
• Pattern 3: Regions
• Pattern 4: Install and redeploy
• Pattern 5: Certification for public connectors
• Pattern 6: The required connector README
• Pattern 7: Troubleshooting
• Checklist

Pattern 1: The connect.yaml configuration contract

• Give every key a clear description — it's what the installer reads in the Merchant Center.
• Provide sensible defaults for standardConfiguration where possible to reduce install friction.
• Put secrets in securedConfiguration (security.md).
• Prefer inheritAs.apiClient.scopes so the platform auto-generates the API client at install — the installer doesn't have to create one.

Pattern 2: Deployment types and lifecycle

Pattern 3: Regions

Pattern 4: Install and redeploy

Pattern 5: Certification for public connectors

Pattern 6: The required connector README

Every connector built with this skill ships a README. It is the install contract for a human operator and a certification artifact. It must state:

• Fail-open vs fail-closed stance per use case — what happens to carts/orders/messages when the external dependency is down (service-applications.md, event-applications.md).
• Required scopes — the exact inheritAs.apiClient.scopes (or the minimal pre-created client scopes), never "admin" (security.md).
• Configuration table — every connect.yaml key (standard and secured), its meaning, whether required, and its default.
• Poison-message / replay runbook — detection, DLQ/containment, and replay procedure (observability-operations.md).

Pattern 7: Troubleshooting

• Deployment failed at postDeploy → a non-zero exit rolls back. Check deployment logs; common causes: missing required config, invalid external credentials (validate them in postDeploy so this is explicit), or an Extension/Subscription key collision.
• Carts/orders suddenly failing after deploy → a fail-closed extension whose endpoint is erroring, or a dangling Extension after an undeploy that didn't clean up (lifecycle-scripts.md). Check the extension destination and /status.
• Messages redelivering forever → a handler returning non-2xx on an unprocessable message (event-applications.md, Pattern 2).
• First request after idle is slow → sandbox cold-start (~15 s); use production for warmed instances.
• Changes not taking effect → Extension/Subscription changes can take up to a minute (eventual consistency); deployment can take ~15 minutes.

Checklist

• commercetools connect validate passes before staging; staged/previewed/published/deployed via the CLI
• Every configuration key has a clear description; sensible defaults on standardConfiguration; secrets in securedConfiguration
• Least-privilege scopes via inheritAs.apiClient.scopes (or documented minimal set)
• Deployed in the same region as the target project
• Redeploy (not delete/recreate) used for config changes; postDeploy is idempotent
• Connector README documents: fail-open/closed stance, required scopes, full configuration table, poison-message/replay runbook
• For public listing: certification requirements reviewed (private connectors skip this)

Event Applications (Subscription Handlers)

The transactional email sub-area (integrations/email/overview.md) is a worked, end-to-end event app built on the patterns below — including the at-most-once vs at-least-once decision for a non-idempotent ESP send.

Table of Contents

• Contract facts (verified)
• Pattern 1: Validate the envelope before processing
• Pattern 2: Acknowledge correctly — redelivery is driven by your status code
• Pattern 3: Filter message types and ignore the rest
• Pattern 4: Idempotency under at-least-once delivery
• Pattern 5: Re-fetch by ID, never trust the payload
• Pattern 6: Self-change filtering
• Pattern 7: Register the Pub/Sub subscription destination
• Checklist

Contract facts (verified)

• At-least-once delivery, no ordering guarantee, no delivery-time guarantee.
• The payload arrives wrapped in the Google Cloud Pub/Sub push envelope, and message.data is base64-encoded. All Google Cloud Platform event payload message.data is base64-encoded (verified: Connect — locally test an event app) — the wrapper is { "message": { "data": "<base64>" } }. The base64 is the Pub/Sub transport, not something commercetools adds; the commercetools notification underneath is plain JSON. Decode it before processing (Pattern 1).
• Ack by status code (Connect event apps): the broker retries unless the app responds 102, 200, 201, 202, or 204. Too many negative acks trigger push backoff.
• Event acknowledgement timeout: 10 seconds. Application request times out after 5 minutes; the broker retains unacknowledged messages for 7 days.
• Delivery identity (for dedup comparisons and logging, not storage): for notificationType: "Message" the resource.id + sequenceNumber; for Change payloads (ResourceCreated/Updated/Deleted) the resource.id + version.
• payloadNotIncluded: if the message exceeds the queue's size limit (often 256 KB) the payload is omitted — you must re-fetch the resource by ID.

Pattern 1: Validate the envelope before processing

const msg = JSON.parse(Buffer.from(req.body.message.data, 'base64').toString());
await process(msg.resource.id);   // throws on any malformed/empty envelope → 500 → redelivered forever

function decodeEnvelope(body: unknown): SubscriptionMessage {
  const message = (body as any)?.message;
  if (!message || typeof message.data !== 'string') {
    throw new BadEnvelope('missing Pub/Sub message data');
  }
  let parsed: SubscriptionMessage;
  try {
    parsed = JSON.parse(Buffer.from(message.data, 'base64').toString().trim());   // base64 → JSON
  } catch {
    throw new BadEnvelope('cannot parse message data');
  }
  if (!parsed.resource?.typeId || !parsed.resource?.id || !parsed.notificationType) {
    throw new BadEnvelope('missing resource reference or notificationType');
  }
  return parsed;
}

Decide deliberately what a malformed envelope returns. A truly un-parseable envelope will never become valid on retry, so returning a 2xx (ack-and-drop, logged) avoids a redelivery loop; some teams prefer a 4xx plus monitoring. Either is defensible — an un-acked 5xx loop is not.

Pattern 2: Acknowledge correctly — redelivery is driven by your status code

This is the single most important event-app decision. The broker redelivers on any non-ack response.

if (!isSupported(message)) {
  throw new CustomError(400, `Resource type ${message.resource.typeId} not supported`);
}

try { await handle(message); } catch (e) { logger.error(e); }   // always falls through to 200
res.status(200).send();

try {
  await handle(message);
  res.status(204).send();                 // handled (or intentionally ignored)
} catch (err) {
  if (isTransient(err)) { res.status(503).send(); return; }   // let the broker retry
  logger.error({ correlationId, err }, 'permanently unprocessable message');
  res.status(200).send();                 // ack; alert/DLQ instead of looping
}

Pattern 3: Filter message types and ignore the rest

Subscribe narrowly, then branch on type and ack anything you don't handle.

switch (message.resource.typeId) {
  case 'order':
    if (isOrderConfirmed(message)) await syncOrder(message.resource.id);
    break;                                  // anything else about orders: ack, do nothing
  default:
    break;                                  // includes the platform's subscription test message
}
res.status(204).send();

Pattern 4: Idempotency under at-least-once delivery

const seen = new Set<string>();             // lost on restart; not shared across instances
if (seen.has(message.id)) return;
seen.add(message.id);

// Let the target system's own idempotency decide: does it already have this resource?
const existing = await external.findByOrderId(orderId);
if (existing) { logger.info({ orderId }, 'already synced; skip'); return; }
await external.create(/* ... */);   // or upsert by a stable key, so a re-run is a no-op

Pattern 5: Re-fetch by ID, never trust the payload

const order = await getOrderById(message.resource.id);   // current truth
if (order.orderState !== 'Confirmed') return;            // re-check against live state

Pattern 6: Self-change filtering

If your handler writes back to commercetools (e.g. sets a custom field on the order), that write can emit a message your subscription receives — a loop.

Pattern 7: Register the Pub/Sub subscription destination

const destination = {
  type: 'GoogleCloudPubSub',
  topic: process.env.CONNECT_GCP_TOPIC_NAME,
  projectId: process.env.CONNECT_GCP_PROJECT_ID,
};

This skill targets GCP-hosted Connect deployments, where the injected destination is Google Cloud Pub/Sub. Don't hardcode a connection string for another broker — always build the destination from the injected CONNECT_GCP_* vars.

Checklist

• Pub/Sub envelope decoded (base64 message.data) and structurally validated (→ JSON → resource ref → notificationType) before processing
• Status codes follow the ack table: 2xx for handled/irrelevant, non-2xx only for retryable failures
• No 4xx/5xx on unsupported-but-subscribed types (no redelivery loop); no blanket error-swallowing (no silent loss)
• Reprocessing is a no-op via stateless means (target's own idempotency, re-fetch-and-re-check, or upsert by stable key) — no local dedup store
• Handler re-fetches the resource by ID; handles payloadNotIncluded
• Self-change filtering prevents write-back loops
• Subscription registers only the needed message types; destination built from the injected CONNECT_GCP_* vars
• Processing stays within the 10 s ack timeout (offload long work; ack fast)

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. → parent 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 Pub/Sub on Connect (GoogleCloudPubSub)"
  - 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-connect" \
  --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 parent 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.

Record the decision, rung, and connector name + version (or "none exists") in the requirements block.

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 chosen 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 parent 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 injected broker is Google Cloud Pub/Sub — build the destination from the injected CONNECT_GCP_* vars, 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, Pub/Sub destination) 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 (parent 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 (parent security.md). Never trust an unauthenticated inbound write to Customers. (AuthorizationHeaderAuthentication 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 (parent 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-connect" \
  --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 parent 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.

Record the decision, the rung, and the version in the requirements block.

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 chosen: 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-connect" \
  --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 parent 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 CONNECT_GCP_* vars.
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 injected CONNECT_GCP_* vars
• 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