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)

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)

Job Applications (Scheduled / On-Demand Batch)

Table of Contents

• Contract facts (verified)
• Pattern 1: Schedule
• Pattern 2: Self-managed concurrency
• Pattern 3: Restart-safe checkpointing within the timeout
• Pattern 4: Stateless idempotency per unit of work
• Checklist

Contract facts (verified)

• Cron-scheduled. properties.schedule in connect.yaml sets the default cron expression; it can be overridden per deployment via the schedule field of the deployment configuration.
• Application request times out after 30 minutes. Work that can't finish in one run must checkpoint and resume.
• No concurrency guard. Connect does not prevent a new scheduled run from starting while a previous one is still going. You own mutual exclusion.
• Isolated container, no shared filesystem. Persist any cross-run state externally (Custom Object / DB / cache).

Pattern 1: Schedule

deployAs:
  - name: nightly-reconcile
    applicationType: job
    endpoint: /job
    properties:
      schedule: '0 1 * * *'      # 01:00 daily; standard 5-field cron

Pattern 2: Self-managed concurrency

Because Connect won't stop overlapping runs, a long run colliding with the next tick can double-process.

// lock stored in a commercetools Custom Object (or your DB)
async function withJobLock(run: () => Promise<void>) {
  const lock = await tryAcquireLock('nightly-reconcile', { ttlMinutes: 35 }); // > job timeout
  if (!lock) { logger.warn('previous run still active; skipping'); return; }
  try { await run(); } finally { await releaseLock(lock); }
}

Set the TTL longer than the 30-minute timeout so a crashed run's lock eventually expires instead of wedging the job forever.

Pattern 3: Restart-safe checkpointing within the timeout

A batch larger than 30 minutes of work must persist progress and resume next run.

let cursor = await loadCursor('nightly-reconcile');      // e.g. lastProcessedId / page token
const deadline = Date.now() + 25 * 60_000;               // stop with margin before the 30-min limit
while (cursor && Date.now() < deadline) {
  const batch = await fetchPage(cursor);
  await processBatch(batch);                              // idempotent per item (Pattern 4)
  cursor = batch.nextCursor;
  await saveCursor('nightly-reconcile', cursor);          // checkpoint after each page
}

Checkpoint frequently so a timeout or crash loses at most one page, and resume from the saved cursor on the next run.

Pattern 4: Stateless idempotency per unit of work

Checklist

• properties.schedule set with headroom over the expected run time; assumed cadence documented in the README
• Overlap protection via a durable lock with a TTL longer than the 30-minute timeout
• Long batches checkpoint a cursor and stop before the 30-minute deadline, resuming next run
• Each unit of work is idempotent statelessly (upsert / check-before-create / compare-and-set) — no dedup store
• Structured logs include a per-run id → observability-operations.md

Lifecycle Scripts (postDeploy / preUndeploy)

Table of Contents

• Pattern 1: Idempotent registration (get-then-update, not delete-then-recreate)
• Pattern 2: Schema-as-code for custom types
• Pattern 3: Deploy-time external dependency validation
• Pattern 4: Clean teardown in preUndeploy
• Pattern 5: Exit codes and platform-injected variables
• Checklist

Pattern 1: Idempotent registration (get-then-update, not delete-then-recreate)

const { body: { results } } = await apiRoot.extensions()
  .get({ queryArgs: { where: `key = "${KEY}"` } }).execute();
if (results.length) {
  await apiRoot.extensions().withKey({ key: KEY })
    .delete({ queryArgs: { version: results[0].version } }).execute();
}
await apiRoot.extensions().post({ body: draft }).execute();   // gap between delete and post

Subscriptions are different — and the public docs example uses delete-then-recreate for them. The event-application postDeploy example deletes and re-creates the Subscription on each deploy, and that's an accepted pattern. A Subscription is not in the synchronous path of any operation: the gap only risks missing change messages emitted during the short delete→recreate window — it never fails the triggering create/update itself. Given at-least-once delivery and the recommendation to re-fetch-and-reconcile by ID (event-applications.md), that milder "missed events" risk is often acceptable. Use get-then-update (below) if you want to close even that window; use delete-then-recreate (matching the docs) if a brief miss is tolerable and reconciliation covers it. For Extensions, get-then-update is the clear choice.

const { body: { results } } = await apiRoot.extensions()
  .get({ queryArgs: { where: `key = "${KEY}"` } }).execute();

if (results.length === 0) {
  await apiRoot.extensions().post({ body: draft }).execute();          // first deploy
} else {
  const current = results[0];
  await apiRoot.extensions().withKey({ key: KEY }).post({ body: {
    version: current.version,
    actions: diffToUpdateActions(current, draft),                      // e.g. setTriggers, changeDestination, changeTimeoutInMs
  }}).execute();                                                       // no gap
}

Pattern 2: Schema-as-code for custom types

async function ensureType(apiRoot, draft) {
  const { body: { results } } = await apiRoot.types()
    .get({ queryArgs: { where: `key = "${draft.key}"` } }).execute();
  if (results.length === 0) {
    await apiRoot.types().post({ body: draft }).execute();
  } else {
    const existing = results[0];
    const missing = draft.fieldDefinitions.filter(
      f => !existing.fieldDefinitions?.some(e => e.name === f.name));
    if (missing.length) {
      await apiRoot.types().withKey({ key: draft.key }).post({ body: {
        version: existing.version,
        actions: missing.map(fieldDefinition => ({ action: 'addFieldDefinition', fieldDefinition })),
      }}).execute();
    }
  }
}

Pattern 3: Deploy-time external dependency validation

Surface bad external credentials at deploy time, not on the first customer request.

const ok = await externalClient.testConnection();
if (!ok) {
  // Decide: warn-and-continue, or fail the deploy. State which in the README.
  process.stderr.write('WARNING: external credentials invalid — connector deployed but non-functional\n');
}

Warning-and-continue is reasonable for a connector that should still deploy; failing fast is reasonable when the connector is useless without the dependency. Choose deliberately and document it.

Pattern 4: Clean teardown in preUndeploy

await deleteExtensionIfPresent(apiRoot, EXTENSION_KEY);
await deleteSubscriptionIfPresent(apiRoot, SUBSCRIPTION_KEY);
await removeCustomTypeFieldsIfPresent(apiRoot, TYPE_KEY);   // remove fields you added; drop the type if you own it

A leftover Extension after undeploy is especially dangerous: it stays registered, its URL is gone, and (if fail-closed) it blocks every triggering operation.

Pattern 5: Exit codes and platform-injected variables

• Exit non-zero on real failure. A non-zero exit from postDeploy/preUndeploy rolls back the deployment. Wrap run() and set process.exitCode = 1 on genuine errors; don't exit non-zero for benign "already exists" cases.
• Use the injected variables rather than guessing URLs/topics (verified: automation scripts):
  • service: CONNECT_SERVICE_URL — the public URL to register as the extension destination.
  • event: CONNECT_GCP_TOPIC_NAME and CONNECT_GCP_PROJECT_ID — build the Google Cloud Pub/Sub destination from these. See event-applications.md, Pattern 7.

Checklist

• Extension registration is get-then-update (create only if absent) — no delete-then-recreate gap (an Extension gap fails live operations); Subscriptions may use get-then-update or the docs' delete-then-recreate, since their gap only risks missed events covered by re-fetch reconciliation
• Custom Types created idempotently (add only missing fields) and removed in preUndeploy
• preUndeploy deletes every resource postDeploy created (no dangling extension/subscription)
• External credentials validated at deploy time; warn-vs-fail decision documented
• Scripts exit non-zero only on genuine failure; benign "already exists" is not an error
• Destination URL/topic read from injected CONNECT_* variables, not hardcoded

Merchant Center CLI

This is a different CLI from the Connect CLI. MC customizations are built with the @commercetools-frontend/* toolchain (create-mc-app, mc-scripts), not @commercetools/cli. The Connect CLI (connect-cli.md) only enters the picture at deploy time, when Connect ships the built bundle (Step 5 there). Don't conflate the two.

Step 1. Scaffold

# Custom application (default):
npx @commercetools-frontend/create-mc-app@latest my-app --template starter

# Custom view:
npx @commercetools-frontend/create-mc-app@latest my-view --application-type custom-view --template starter

Step 2. The mc-scripts toolchain

Step 3. Pin versions

Step 4. Develop and authenticate locally

mc-scripts login    # authenticate against a real project (one-time, opens a browser)
mc-scripts start    # http://localhost:3001

Flags and options can evolve — confirm with npx @commercetools-frontend/mc-scripts --help and the Merchant Center CLI docs. Source of truth for platform behavior: docs.commercetools.com/merchant-center-customizations.

Merchant Center Custom Applications & Views

Table of Contents

• Contract facts (verified)
• Pattern 1: Custom application vs custom view
• Pattern 2: The config-file contract
• Pattern 3: Permissions
• Pattern 4: Develop and test locally
• Pattern 5: Deploy via Connect (the vessel)
• Checklist

Contract facts

• A customization is a hosted React application built on the application-shell; the Merchant Center loads it from a URL you control. It is not a backend service — there is no inbound webhook, no Subscription, no endpoint.
• It runs in the operator's authenticated session: it inherits the logged-in user's project and permissions, and calls the commercetools APIs (and your own) on their behalf via the MC's proxy. There is no machine-to-machine API client for the UI itself.
• entryPointUriPath (apps) is unique per cloud Region environment and fixes the serving route; it cannot collide with another customization in the same Region.

Pattern 1: Custom application vs custom view

• Custom application — a standalone destination with its own route and a main-menu entry, reachable from anywhere in the Merchant Center. Use it when the functionality doesn't belong inside a built-in application (a bespoke dashboard, an integration console, a bulk tool).
• Custom view — an embedded CustomPanel rendered inside an existing built-in MC page (e.g. a panel on the product detail page). Use it when the functionality augments a built-in app and you want to keep the operator in context instead of sending them to a separate screen. A view declares locators (which MC locations it may render in) and typeSettings.size (SMALL/LARGE) instead of menu links.

Pattern 2: The config-file contract

• Identity & routing — entryPointUriPath (apps, unique per cloud Region environment) or type: CustomPanel + locators (views).
• Region — cloudIdentifier (e.g. gcp-eu); must match the project's region.
• env.development — initialProjectKey, teamId: which project/team and permission set you run against locally.
• env.production — applicationId (apps) / customViewId (views) and url: the registered ID and the hosting URL.
• Permissions — oAuthScopes (the default view/manage pair) and optional additionalOAuthScopes (Pattern 3).
• Navigation (apps) — mainMenuLink / submenuLinks, each with their own required permissions.

Pattern 3: Permissions

Pattern 4: Develop and test locally

• Jest with the @commercetools-frontend/jest-preset-mc-app preset.
• The application-shell test-utils: renderAppWithRedux (applications) and renderCustomView (views), so components mount with a realistic shell.
• Drive permission paths explicitly (a view-only user must not see manage controls).
• Cypress for end-to-end flows.

Pattern 5: Deploy via Connect (the vessel)

deployAs:
  - name: my-app
    applicationType: merchant-center-custom-application
    configuration:
      standardConfiguration:
        - key: CUSTOM_APPLICATION_ID
          description: the Custom Application ID
          required: true
        - key: ENTRY_POINT_URI_PATH
          description: The Application entry point URI path
          required: true
        - key: CLOUD_IDENTIFIER
          description: The cloud identifier
          default: 'gcp-eu'

1. Register the custom app/view in the Merchant Center with a placeholder URL → obtain its ID (CUSTOM_APPLICATION_ID / CUSTOM_VIEW_ID).
2. Scaffold a Connect-shaped project containing the MC app/view (→ merchant-center-cli.md).
3. Wire the config file's ${env:...} placeholders and add the connect.yaml block above.
4. Push to git and cut a release tag.
5. Stage → publish → deploy with the Connect CLI: connectorstaged create → publish → deployment create, supplying the ID, entry-point path, and region — exact commands and flags in connect-cli.md Step 5.
6. Retrieve the deployed URL from the deployment.
7. Update the Merchant Center registration, replacing the placeholder URL with the deployed one.

Checklist

• App-vs-view chosen deliberately (own route/menu → application; embedded CustomPanel → view)
• Config file uses ${env:...} placeholders for applicationId/customViewId, url, and entryPointUriPath — no hardcoded per-project values
• oAuthScopes requests only what the UI uses; UI gated with useIsAuthorized and menu-link permissions
• Run and tested locally via the application-shell (mc-scripts start, jest-preset + renderAppWithRedux/renderCustomView), including a permission-denied path
• connect.yaml uses the correct merchant-center-* applicationType with no stray endpoint, securedConfiguration, or APPLICATION_URL
• Register-first / update-URL-last sequence followed; deployed in the project's region with a matching cloudIdentifier

Monorepo: Connector + Storefront

• Connector internals (scaffold, shared/ folder, route↔endpoint, connect.yaml fields) → project-structure.md.
• connect.yaml configuration contract and deploy lifecycle → deployment-installation.md, CLI commands → connect-cli.md.
• Merchant Center custom app/view (scaffold, register, deploy via Connect) → merchant-center-cli.md, merchant-center-customizations.md.
• Storefront layout, framework wiring, and its deploy → the commercetools-storefront skill and its stack adapter.

Table of Contents

• Pattern 1: The layout
• Pattern 2: Why this shape (the constraints)
• Pattern 3: Two independent deploy lifecycles
• Pattern 4: One repo or two?
• Checklist

Pattern 1: The layout

<repo root>/
├── connect.yaml          # Connect: declares every backend app — MUST be at the repo root
├── package.json          # tooling hub only (dev scripts, install:all) — NOT an npm-workspaces root
│
├── orders/               # Connect service app   ─┐  each folder name == its connect.yaml `name`
├── inventory/            # Connect event app      ─┤  (only [A-Za-z0-9_-], no slashes →
├── merchant-center-app/  # Connect MC custom app  ─┘   the apps can only be root siblings)
├── shared/               # plain shared-code folder, imported by relative path (Pattern 3 below)
│
├── vercel.json           # storefront deploy config  ┐  owned by the storefront skill —
├── netlify.toml          # storefront deploy config  ┘  see its stack adapter, don't hand-author here
└── <root-dir>/                 # the storefront — deploys independently of Connect

Pattern 2: Why this shape (the constraints)

Three platform facts force the layout; none are negotiable:

• connect.yaml lives at the repo root, and deployAs[].name maps to a sibling folder. Each app's name allows only [A-Za-z0-9_-] — no slashes — so a connectors/orders/ nesting is impossible; backend apps can only be root siblings (verified: connect.yaml reference; see project-structure.md).
• No npm workspaces. Connect clones the whole repo, then runs npm install and the build script from inside each app folder — never once from a workspace root. A root package.json with a "workspaces" field would therefore make every app's install pull in all workspace packages: bigger installs, version conflicts, surprises. So keep each connector app self-contained (its own dependencies), keep the root package.json a tooling hub only (dev scripts), and share code through a plain shared/ folder imported by relative path (per project-structure.md) — a shared folder is fine; a workspaces root is not.
• The storefront is not a Connect app. It has no entry in connect.yaml and deploys on its own (Pattern 3). Connect ignores it; it must ignore Connect.

Pattern 3: Two independent deploy lifecycles

Optionally skip a half's CI build when only the other half changed (e.g. a Vercel ignoreCommand) — a storefront-deploy detail; configure it per the storefront skill, not here.

Pattern 4: One repo or two?

Checklist

• connect.yaml at the repo root; every backend app is a root-sibling folder whose name matches its deployAs[].name
• Root package.json is a tooling hub only — no "workspaces"; each connector app is self-contained
• Shared connector code in a plain shared/ folder, imported by relative path (not via npm workspaces)
• Storefront lives in its own root-sibling dir <root-dir>; its deploy is scoped to that dir per the storefront skill
• Connector + MC app deployed via Connect; storefront deployed via Vercel/Netlify — two independent lifecycles
• MC custom app (if any) follows the register-first / update-URL-last sequence → merchant-center-customizations.md

Observability & Operations

Table of Contents

• Pattern 1: Structured logs with correlation IDs
• Pattern 2: Health endpoint
• Pattern 3: Runtime feature flags
• Pattern 4: Accessing deployment logs
• Pattern 5: Poison-message / replay runbook
• Checklist

Pattern 1: Structured logs with correlation IDs

JSON logs are searchable; a correlation key ties every line of one request together and back to the originating commercetools call.

import { createApplicationLogger } from '@commercetools-backend/loggers';
export const logger = createApplicationLogger({ json: true });

The correlation key depends on the app type:

• Service (extension): the X-Correlation-ID request header — commercetools sets it and returns the same value to the original API caller, so logging it links your logs to the caller's. (verified: API Extensions — Headers)
• Event: resource.id + sequenceNumber (Message) or resource.id + version (Change) — the same fields used for idempotency, so a duplicate is recognizable in logs.

const correlationId = req.get('x-correlation-id') ?? `${msg.resource.id}:${msg.sequenceNumber}`;
const log = logger.child({ correlationId, resourceId: msg.resource.id });
log.info({ type: msg.type }, 'processing message');     // identifiers, not the payload body

Pattern 2: Health endpoint

Expose a cheap liveness route that touches no secrets and does no external work.

router.get('/status', (_req, res) => res.status(200).json({ status: 'UP' }));

Pattern 3: Runtime feature flags

Gate each independent behavior behind a config flag so an operator can disable one sync direction without redeploying code.

if (readConfiguration().featOrderSyncActive !== 'true') {
  logger.info('order sync disabled by feature flag');
  return res.status(204).send();                  // still ack the message
}

Pattern 4: Accessing deployment logs

Pattern 5: Poison-message / replay runbook

• Detection: what does a poison message look like in logs (repeated correlation key, rising delivery count)? Set an alert on the Subscription health and/or a retry-count threshold.
• Containment: on a terminal (non-retryable) error, ack (2xx) and route the message to a dead-letter store — a Custom Object, a DLQ on your queue, or a logged record — rather than returning non-2xx and looping. Recall the Subscription retries a TemporaryError for up to 48 hours before dropping the message (verified: Subscriptions — Delivery) — so a true poison message left un-acked wastes retries for 48 hours and then silently vanishes.
• Replay: how does an operator reprocess after a fix? Because handlers re-fetch by ID and are idempotent, replay is usually "re-emit the resource id" — e.g. a small job or admin route that re-runs processing for a given resource.id from the dead-letter store.

State the chosen DLQ mechanism, the alert, and the replay procedure explicitly; "we retry forever" is not a runbook.

Checklist

• Logs are structured JSON and carry a correlation key on every line (X-Correlation-ID for service; resource.id+sequenceNumber/version for event)
• Request bodies/PII are not logged — identifiers only
• A fast, unauthenticated /status liveness endpoint exists
• Independent behaviors are gated behind runtime feature flags; disabling a path still acks messages
• Poison-message detection, containment (DLQ/ack), and replay procedure documented in the README
• Subscription health alerting recommended for production-critical connectors

Project Structure

Table of Contents

• Pattern 1: Scaffold with the Connect CLI
• Pattern 2: Match the route path to the connect.yaml endpoint
• Pattern 3: Multi-application layout and the shared workspace
• Pattern 4: commercetools client setup
• Pattern 5: connect.yaml anatomy
• Pattern 6: Fail-fast environment validation
• Pattern 7: Typed SDK usage at the boundary
• Local development with the CLI
• Checklist

Pattern 1: Scaffold with the Connect CLI

my-connector/
├── connect.yaml                 # declares every application
└── service/
    ├── src/
    │   ├── index.ts             # express bootstrap (listens on the platform-provided port)
    │   ├── app.ts               # mounts the router at the endpoint path; error middleware
    │   ├── routes/              # router (+ a /status health route)
    │   ├── controllers/         # request handlers
    │   ├── client/              # build.client.ts (ClientBuilder) + create.client.ts (apiRoot)
    │   ├── connector/           # post-deploy.ts, pre-undeploy.ts, actions.ts
    │   ├── middleware/          # auth, error, http
    │   ├── validators/          # env validation
    │   ├── utils/               # config, logger
    │   └── types/ interfaces/
    ├── tests/                   # jest (the template seeds an integration spec)
    ├── package.json             # scripts: build, start, start:dev, test, connector:post-deploy…
    └── tsconfig.json

Pattern 2: Match the route path to the connect.yaml endpoint

// connect.yaml →  endpoint: /service
app.use('/', serviceRouter);          // app serves POST / , platform calls POST /service → 404

// connect.yaml →  endpoint: /service
app.use('/service', serviceRouter);   // app.ts
// routes/service.route.ts
serviceRouter.post('/', handler);      // full path = POST /service
serviceRouter.get('/status', liveness);

Pattern 3: Multi-application layout and the shared workspace

my-connector/
├── connect.yaml
├── service-a/  service-b/   event/   job/      # one per application; name matches connect.yaml
└── shared/src/                    # client, errors, middleware, validators, types, mappers

Pattern 4: commercetools client setup

Pattern 5: connect.yaml anatomy

deployAs:
  - name: service                 # must match the folder name
    applicationType: service
    endpoint: /service             # must match your route mount (Pattern 2)
    scripts:                       # optional — only if you create Extensions/Subscriptions/Types
      postDeploy: npm ci && npm run build && npm run connector:post-deploy
      preUndeploy: npm ci && npm run build && npm run connector:pre-undeploy
    configuration:
      standardConfiguration: [ { key: CTP_REGION, description: …, required: true } ]   # non-secret
      securedConfiguration: [ { key: EXTERNAL_API_KEY, description: …, required: true } ]  # secrets
  - name: nightly-reconcile
    applicationType: job
    endpoint: /job
    properties: { schedule: '0 1 * * *' }   # cron; required for job; overridable per deployment
inheritAs:
  apiClient:
    scopes: [ manage_orders, manage_subscriptions, manage_extensions ]   # least-privilege; platform generates the client

Pattern 6: Fail-fast environment validation

let cached: Config | undefined;
export function readConfiguration(): Config {
  if (cached) return cached;
  const cfg = { region: process.env.CTP_REGION, externalApiKey: process.env.EXTERNAL_API_KEY };
  const errors = validate(cfg);            // typed rules: present, length, format, enum
  if (errors.length) throw new Error(`Invalid environment configuration: ${errors.join('; ')}`);
  return (cached = cfg as Config);
}

Pattern 7: Typed SDK usage at the boundary

import type { Order } from '@commercetools/platform-sdk';
const order: Order = await getOrderById(resourceId);   // typed end to end
const dto = toExternalOrder(order);                     // map in shared/src/mappers

Local development with the CLI

Checklist

• Project scaffolded with commercetools connect init (not hand-rolled); built on the template structure
• One folder per deployAs entry; folder name matches application name
• Express router mounted at the same base path as connect.yaml endpoint; /status reachable
• Pinned versions: @commercetools/ts-client@^4 + @commercetools/platform-sdk@^8 (not sdk-client-v2); Java spring-boot-starter-parent 3.x+ & commercetools Java SDK 19+; apiRoot built once and reused
• Shared code in a single shared/ workspace (multi-app connectors); imported, not duplicated
• Secrets only in securedConfiguration; least-privilege inheritAs.apiClient.scopes
• readConfiguration() validates all env vars once at startup and throws on invalid; app is stateless
• SDK types end to end; no any escapes; no dead code
• commercetools connect validate passes; commercetools connect application test runs the suite

Security

Table of Contents

• Pattern 1: Authenticate every inbound endpoint
• Pattern 2: Validate JWTs fully
• Pattern 3: Least-privilege commercetools scopes
• Pattern 4: Secrets in securedConfiguration
• Pattern 5: Error hygiene
• Checklist

Pattern 1: Authenticate every inbound endpoint

Two kinds of inbound endpoint, both must be authenticated:

1. API extension endpoint — called by commercetools. Register destination auth and verify it in-app (see service-applications.md, Pattern 1). commercetools sends the Authorization header (or x-functions-key) you configured.
2. External webhook endpoint — called by a third-party system pushing events to your connector. Authenticate with a full JWT or a shared secret the external system signs.

serviceRouter.post('/', handleExtension);          // no auth middleware
serviceRouter.use(['/admin'], verifyJWT);          // auth only on a different route

router.get('/status', statusHandler);              // liveness only, no secrets
router.post('/', verifyInbound, handler);          // every processing route authenticated

Pattern 2: Validate JWTs fully

const { payload } = jwt.decode(token, { complete: true });   // decode ≠ verify; signature unchecked
if (payload.iss === expectedIssuer) next();                   // trivially forged

import { verify } from 'jsonwebtoken';
const payload = verify(token, secret, {
  algorithms: ['HS256'],        // pin; never allow 'none' or caller-chosen alg
  issuer: cfg.jwtIssuer,
  audience: cfg.jwtAudience,
  subject: cfg.jwtSubject,
  ignoreExpiration: false,
});

Pattern 3: Least-privilege commercetools scopes

inheritAs:
  apiClient:
    scopes:
      - manage_orders
      - manage_subscriptions   # only if an event app uses Subscriptions
      - manage_extensions      # only if a service app uses API Extensions

Pattern 4: Secrets in securedConfiguration

Pattern 5: Error hygiene

Error responses and logs must not leak stack traces, secrets, or internals to callers.

export const errorMiddleware = (err, _req, res, _next) => {
  const dev = process.env.NODE_ENV === 'development';
  if (err instanceof CustomError) {
    return res.status(err.statusCode).json({ message: err.message, ...(dev && { stack: err.stack }) });
  }
  res.status(500).json({ message: dev ? String(err) : 'Internal server error' });
};

Checklist

• Every processing endpoint authenticated (extension destination auth + in-app check; webhooks via full JWT/secret); only /status is open
• JWT validation checks signature, issuer, audience, subject, expiry, and pins the algorithm (no alg: none)
• Scopes are least-privilege via inheritAs.apiClient.scopes (or a documented minimal set) — never admin/manage_project
• All secrets in securedConfiguration; none hardcoded or in standardConfiguration; secrets never logged
• Error responses hide stack traces and internals in production
• Request bodies/PII not logged; only identifiers and correlation keys

Service Applications (HTTP Endpoints)

• API Extension (commercetools → you): registered as an API Extension in postDeploy, commercetools calls it synchronously after processing a create/update but before persistence; it can validate (reject) or return up to 100 update actions. This mode carries the strict 2 s/10 s response limit. → Patterns 1–6.
• Inbound webhook / API (external system → commercetools): an external system calls it to push data into commercetools; you authenticate the caller, validate the payload, and write to commercetools via the SDK yourself. No Extension is registered, and the 2 s/10 s limit does not apply — the 5-min service timeout does. → Pattern 7.

Table of Contents

• Contract facts (verified)
• Pattern 1: Authenticate the extension destination
• Pattern 2: Trigger conditions — don't fire when you can't act
• Pattern 3: Timeout budget
• Pattern 4: Fail-open vs fail-closed
• Pattern 5: Minimize work on the hot path
• Pattern 6: Response format
• Pattern 7: Inbound webhook mode (external system → commercetools)
• Checklist

Contract facts (verified)

Patterns 1–6 below are the API Extension mode. For the inbound webhook mode, jump to Pattern 7 — the timeout and response-format facts here are extension-specific and do not apply to it.

• Timeouts: connection limit 1 s; response limit 2 s default, configurable via timeoutInMs up to 10 s (higher needs a per-project performance review). Aim to respond fast — ~50 ms for simple validation.
• Coupling: "If it fails or takes a second longer to return, the whole API call fails or takes a second longer." Applied to all clients, including the Merchant Center.
• Extensible resources: carts, orders, payments, payment-methods, customers, customer-groups, quote-requests, staged-quotes, quotes, business-units, shopping-lists. Max 25 extensions per project.
• Response: HTTP destination returns 200/201 for success (empty body or update actions), 400 with an errors array for validation failure. Any other status = failure to respond.
• Headers in: X-Correlation-ID is provided and echoed to the original API caller — log it. Authorization / x-functions-key set if you configured destination auth.
• additionalContext.includeOldResource: true adds oldResource to Update payloads (not Create) — use it to diff what changed.

Note: the Connect service request timeout (5 minutes) and autoscaling are separate platform facts; the binding constraint for an extension is the 2 s / 10 s extension response limit, not 5 minutes.

Pattern 1: Authenticate the extension destination

await apiRoot.extensions().post({ body: {
  key, destination: { type: 'HTTP', url: serviceUrl },   // no authentication block
  triggers: [...],
}}).execute();

// registration (post-deploy)
await apiRoot.extensions().post({ body: {
  key,
  destination: {
    type: 'HTTP',
    url: serviceUrl,
    authentication: { type: 'AuthorizationHeader', headerValue: `Bearer ${sharedSecret}` },
  },
  triggers: [...],
}}).execute();

// handler: reject anything without the expected secret
function assertAuthorized(req: Request) {
  if (req.get('authorization') !== `Bearer ${readConfiguration().extensionSecret}`) {
    throw new Unauthorized();
  }
}

Pattern 2: Trigger conditions — don't fire when you can't act

triggers: [{
  resourceTypeId: 'cart',
  actions: ['Create', 'Update'],
  condition: 'shippingAddress is defined AND lineItems is not empty',
}]

Pattern 3: Timeout budget

Your outbound calls must finish inside the extension response limit, with margin.

const controller = new AbortController();
const t = setTimeout(() => controller.abort(), 1500);   // < the 2s extension limit, leaving margin
try {
  const res = await fetch(externalUrl, { signal: controller.signal });
  // ...
} finally { clearTimeout(t); }

Pattern 4: Fail-open vs fail-closed

• Fail-open: on error, return success with no update actions so the cart/order proceeds (possibly without your enrichment). Right when the operation must not be blocked (e.g. optional enrichment, non-blocking validation).
• Fail-closed: on error, return a 400 so the operation is rejected. Right only when proceeding would be incorrect or unsafe (e.g. compliance validation that must hold).

catch (error) { return { statusCode: 400, error: error.message }; }   // any outage blocks ALL carts

catch (err) {
  logger.error({ correlationId, err }, 'external dependency failed');
  if (FAIL_OPEN) return res.status(200).end();          // proceed without enrichment
  return res.status(400).json({ errors: [{ code: 'General', message: 'validation unavailable' }] });
}

Pattern 5: Minimize work on the hot path

The extension fires on every matching create/update. Skip the expensive external call when nothing relevant changed.

const hash = hashTaxRelevantFields(cart);                 // address, line items, quantities…
if (hash === cart.custom?.fields?.lastHash && cart.taxedPrice) {
  return res.status(200).end();                           // nothing changed → no external call, no actions
}
const actions = await computeAndBuildActions(cart);
actions.push(setHashAction(hash));                        // store the new hash for next time
return res.status(200).json({ actions });

Pattern 6: Response format

• Success, no changes: 200/201, empty body (or empty actions).
• Updates: 200/201 with { "actions": [ ... ] } — up to 100 actions, each a valid update action for that resource type. Return well-formed, domain-correct actions (e.g. for external tax on a cart: changeTaxMode → ExternalAmount, then setLineItemTaxAmount / setCartTotalTax.
• Validation failure: 400 with { "errors": [{ "code": "InvalidInput", "message": "..." }] } — code must be a known error code; optional localizedMessage, extensionExtraInfo.

Pattern 7: Inbound webhook mode (external system → commercetools)

The discipline is different from an extension — you own the whole write:

1. Authenticate the caller. The endpoint is public; validate a shared secret or a full JWT on every request (see security.md). This is not optional just because commercetools isn't the caller.
2. Validate the payload before trusting it; reject malformed input with a 4xx.
3. Write idempotently. The same update may be delivered twice (most senders retry). Upsert by a stable key, don't blind-create.
4. Return a status the caller can act on — 2xx on success, 4xx on bad input, 5xx on a transient failure so the sender retries.

router.post('/products', async (req, res) => {
  await apiRoot.products().post({ body: toProductDraft(req.body) }).execute();  // duplicates on retry
  res.status(201).end();
});

router.post('/products', verifyInbound, async (req, res) => {
  const draft = toProductDraft(validatePayload(req.body));   // 400 on invalid
  try {
    const existing = await getProductByKey(draft.key);       // stable external key
    if (existing) {
      await apiRoot.products().withKey({ key: draft.key })
        .post({ body: { version: existing.version, actions: diffToActions(existing, draft) } }).execute();
    } else {
      await apiRoot.products().post({ body: draft }).execute();
    }
    res.status(200).json({ key: draft.key });
  } catch (err) {
    if (isVersionConflict(err)) return res.status(409).end();   // sender may retry; you re-read & re-apply
    logger.error({ correlationId, err }, 'inbound upsert failed');
    res.status(503).end();                                       // transient → let the sender retry
  }
}

Checklist

• Destination registered with AuthorizationHeader (or AzureFunctions) auth, and the secret validated in-app
• Trigger condition set so the extension only fires when it can actually act
• Outbound calls have an explicit timeout under the extension response limit; timeoutInMs set deliberately if >2 s
• Fail-open vs fail-closed decided per use case and documented in the README
• Hot-path work skipped when relevant inputs are unchanged (hash/signature compare)
• Responses use the correct format: 200/201 (+ actions) or 400 (+ errors with valid codes)

• Caller authenticated (shared secret or full JWT) on every request
• Payload validated; malformed input rejected with 4xx
• Write is idempotent — upsert by a stable key, never blind-create; version conflicts handled
• Status codes let the sender retry safely (2xx / 4xx / 5xx); Import API considered for bulk

• X-Correlation-ID (or your own correlation key) logged on every line → observability-operations.md

Testing

Checklist

• Parameterized auth rejection matrix covering missing/malformed/alg:none/wrong-signature/wrong-issuer/wrong-audience/wrong-subject/expired, plus a valid-token accept case
• Envelope tests decode the Pub/Sub wrapper (base64 message.data) and reject malformed input per the chosen contract → event-applications.md, Pattern 1
• Ack-contract tests: 2xx for handled/irrelevant, non-2xx for transient failure
• Idempotency test: same message twice → one side effect
• Router-level tests use supertest + msw with onUnhandledRequest: 'error'
• Hot-path skip asserted (external call not made when inputs unchanged)
• Lifecycle scripts tested for idempotency (no delete-then-recreate)