commercetools

View saved version →

---
name: commercetools-aihub
description: "Exports a selected set of commercetools products (by product selection, category, product type, SKU, product key, store assortment or query predicate) for commercetools AI Hub across vendors (OpenAI Commerce feed, OpenAI Ads feed, Google Merchant Center and Microsoft Merchant Center, including supplemental feeds). Downloads once, then works offline. Maps product data to each vendor spec, checks every vendor's required fields, writes a working file per vendor for the business team to complete, and converts the completed file into the vendor upload format (.jsonl.gz, .tsv, .txt) with upload guidance, including OpenAI manual upload. Use when exporting products for ChatGPT shopping or AI Hub, checking feed readiness or missing required fields, building a supplemental feed, or converting an edited feed file for upload. Not for building or deploying the Connect feed connector itself (see commercetools-connect) and not for loading a catalog into commercetools (see commercetools-catalog-migration)."
when_to_use:
  - "Exporting a product selection, category, product type or SKU list from commercetools for the OpenAI Commerce feed, OpenAI Ads feed, Google or Microsoft"
  - "Checking which products are missing fields the OpenAI, Google or Microsoft product feed specs require"
  - "Building a Google Merchant Center or Microsoft Merchant Center supplemental feed from commercetools data"
  - "Turning a feed file the business team completed in a spreadsheet into the vendor upload format"
  - "Mapping commercetools attributes (brand, GTIN, color, size) and categories to feed fields"
  - "Automating recurring feed delivery from a Connect application — see commercetools-connect"
metadata:
  contentType: SKILL
  area:
    - Integrations
  docsSearch:
    products:
      - AI Hub
      - Composable Commerce
---

# commercetools AI Hub product feeds

AI Hub feeds go to several vendors: OpenAI Commerce feed (ChatGPT shopping), OpenAI Ads feed,
Google Merchant Center and Microsoft Merchant Center. "AI Hub" names the whole export, not one vendor.

Exports what commercetools has for a product selection, per vendor, as a **semi-finished
working file**: every row, every vendor field, blanks where commercetools has no value, and a
note per row listing the required fields it is missing. The business team completes the file
offline; the completed file comes back and is converted, unchanged, into the vendor upload
format. The merchant decides what and when to upload; the skill supplies facts and guidance.

```
aihub_feeds.py fetch     commercetools          ─► <run>/raw/                 products, categories, Store, manifest
aihub_feeds.py build     raw + mapping + specs  ─► <run>/working/<vendor>-working.csv, report/, NEXT-STEPS.md
   (business team completes the working files offline)
aihub_feeds.py finalize  completed file         ─► <out>/<vendor upload file> + finalize report
```

`scripts/aihub_feeds.py` (Python 3.9+, standard library only) is the whole toolchain; run
`aihub_feeds.py <command> --help` for options. The network is used for the download and to
read the vendors' current specs; the specs are cached per run, so rebuilding and finalizing
work offline.

Run it with `python3 scripts/aihub_feeds.py` (`py -3` on Windows, where `python3` is often
missing or a Microsoft Store stub). When no Python 3.9+ is found, tell the user to install it
from python.org and stop; do not rewrite the script in another language.

Vendor specs are **not hardcoded**: `build` and `finalize` read each vendor's published spec
at runtime (fields, required/conditional/optional, allowed values, length limits, Microsoft's
supplemental fields) and merge it with the code that maps commercetools data to fields. New
spec fields become empty columns, removed ones are dropped, and the report lists both. See
[references/vendors.md](references/vendors.md#specs-are-read-at-runtime).

## Data integrity: commercetools is the only source of pr

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: commercetools-catalog-migration
description: Migrates a product catalog from any source system into commercetools through a canonical NDJSON feed contract — the pipeline never parses the source, so each engagement writes only a small adapter. Covers the feed contract, writing an adapter, ProductType derivation and its irreversible attribute constraints, decimal-to-minor-unit money conversion, project-wide slug allocation, category order hints, opening stock per SKU and supply channel, tax categories, and the offline audit gate. Use when migrating or bulk-loading a product catalog into commercetools, writing an adapter for a source export, deciding SameForAll versus CombinationUnique, converting prices to centAmount, or diagnosing rejected Import API operations. Covers loading a catalog from a source system into commercetools — not the Classic-to-Modular catalog model migration of an existing project, which is the staged Modular Catalog migration guide. Not for ongoing sync after cutover, and not for customers, orders, carts, or promotions.
when_to_use:
  - "Migrating or bulk-loading a product catalog from a source system into a commercetools project"
  - "Writing an adapter that turns a source export (hybris ImpEx, PIM extract, CSV) into a catalog feed"
  - "Deciding SameForAll versus CombinationUnique for a variant attribute, or any other irreversible ProductType choice"
  - "Diagnosing Import API operations that were accepted but came back rejected or unresolved"
metadata:
  contentType: SKILL
  area:
    - Migrations
  docsSearch:
    products:
      - Composable Commerce
---

# commercetools catalog migration

Migration is one-time and decision-heavy. The deliverable is **a reviewed set of
decisions**, not a loaded dataset: what was translated, what was approximated,
and what was lost, with a rationale per decision. A migration claiming zero
information loss is not being honest.

If the work is a recurring sync from a PIM, ERP or OMS, this is the wrong
approach: that is integration, contract-heavy rather than decision-heavy.

## The source boundary is a data contract, not a code module

```
any source  →  adapter  →  canonical catalog feed  →  pipeline  →  commercetools
               per          NDJSON, schema-checked    reusable
               engagement   THE CONTRACT
```

The pipeline — [`commercetools/ct-catalog-migration-pipeline`](https://github.com/commercetools/ct-catalog-migration-pipeline),
cloned beside the engagement — **never parses a source system**. It defines a
feed contract and starts there. Everything source-specific lives in the adapter,
upstream of the contract.

This is not decoration. A universal parser for any source platform does not
exist — no two installations agree on their type system — so source knowledge
inside the pipeline is what destroys retargetability. A seam made of *data*
rather than *code* makes that coupling impossible rather than discouraged. The
contract is `schema/catalog-feed.schema.json` in that repository; treat it as
the API.

## Before you start

1. <!-- ct:docs-search:begin -->
   **Docs search (required, run first)** — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the skill text alone:

   ```bash
   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "<extract key terms: Import API, ProductType attributes, catalog model, Standalone Prices, Category slug>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 10
   ```

   Pass t

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 11 — file references are metadata, not package contents.

View saved version →

---
name: commercetools-checkout
description: The Checkout — payment-only mode (integrating Checkout for payments while owning the rest of the flow), full hosted checkout (checkoutFlow), widget integration via @commercetools/checkout-browser-sdk, configuration, PSP connector setup (Stripe, Adyen, Mollie), and webhook handling. Use when integrating Checkout (the product) into a storefront or headless app — not for generic cart-to-order patterns (see commercetools-storefront).
when_to_use:
  - "Integrating the Checkout into a storefront or headless app"
  - "Setting up payment-only mode while keeping existing address and shipping flows"
  - "Configuring PSP connectors such as Stripe, Adyen, or Mollie"
  - "Handling payment webhooks and order confirmation"
  - "Implementing a spec/plan/tasks.md task annotated [SKILL: commercetools-checkout]"
  - "An implementation-plan step that integrates the Checkout, payment sessions, or PSP connectors"
metadata:
  contentType: SKILL
  area:
    - Foundations
  docsSearch:
    products:
      - Composable Commerce
      - Checkout
      - Connect
      - AI Hub
---

# Checkout

The Checkout provides hosted payment and checkout experiences via the Browser SDK.

## Integration Modes

Three modes — choose based on how much of the checkout flow Checkout should own:

- **`paymentFlow`** (payment-only) — keep existing address/shipping UI, replace only the payment step with the Checkout widget. Least invasive.
- **`checkoutFlow`** (full hosted) — replace the entire multi-step checkout with a single commercetools-hosted page covering address, shipping, and payment.
- **`expressPayment`** — add Apple Pay / Google Pay express buttons to cart or PDP. Can coexist with either mode above.

## Workflow

When this skill is invoked, always follow these steps:

1. <!-- ct:docs-search:begin -->
   **Docs search (required, run first)** — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the skill text alone:

   ```bash
   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "<extract key terms from user's question>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 20
   ```

   Pass the commercetools project key and region (as in `api.{region}.commercetools.com`) only if already in your context; otherwise omit both. Never search files or ask the user for them.
   <!-- ct:docs-search:end -->

2. **Combine with skill references** — Cross-reference the analysis output with local references in `./references/` for complete context.

3. **Provide implementation guidance** — Synthesize the documentation with the specific integration mode the user is targeting.

### Optional scripts

**Fetch GraphQL schema** — Run this when you need context about a commercetools GraphQL query or mutation — for example, to inspect a resource's fields, types, and available operations before writing a query, or to verify a GraphQL query/mutation you have just generated against the real schema. It fetches the partial GraphQL SDL for a single commercetools resource:
   ```bash
   node scripts/graphql-schemata.mjs \
     --resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>"
   ```
   The output is the GraphQL SDL for that resource. If the resource name is not recognized, the script prints the list of valid resource names — pick the correct one and re-run. *

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: commercetools-commerce-patterns
description: Surface-independent commerce domain logic — pricing models (customer groups, channel fallback, high-precision money), discount stacking (Product/Cart/Code/Direct/Groups), shipping predicates and cart score, tax modes, payment object modeling, Import API bulk patterns, and catalog architecture. Use for commerce-domain questions that are independent of surface (storefront, MC app, Connect).
when_to_use:
  - "Pricing models: customer group pricing, channel price fallback, high-precision money, limited-time pricing"
  - "Discount stacking order, Direct Discounts blocking Discount Codes, sortOrder semantics"
  - "Cart Discounts: Buy/Get, Discount Bundles, BOGO, spend thresholds, Discount Groups"
  - "Shipping predicates, cart score tiers, price functions, dynamic shipping rate calculation"
  - "Tax modes: Platform, External, ExternalAmount, Disabled — when to use each"
  - "Payment object modeling — PSP transaction states, interfaceId immutability, tax services"
  - "Import API: batch size limits, ordering guarantees, productDraftImport vs productVariantPatch"
  - "Catalog architecture: ProductType design, bundle patterns, item substitutes, inventory modeling"
  - "B2B order flows: Business Unit hierarchy, as-associate API, approval rules, quote lifecycle"
  - "Recurring orders: RecurrencePolicy, priceSelectionMode, recurringOrderScope"
  - "Implementing a spec/plan/tasks.md task annotated [SKILL: commercetools-commerce-patterns]"
  - "An implementation-plan step covering pricing, discounts, tax, shipping, catalog, or B2B domain modeling"
metadata:
  contentType: SKILL
  area:
    - Foundations
  docsSearch:
    products:
      - Composable Commerce
      - Checkout
      - Connect
      - InStore
      - AI Hub
---

## Workflow

When this skill is invoked, always follow these steps:

1. <!-- ct:docs-search:begin -->
   **Docs search (required, run first)** — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the skill text alone:

   ```bash
   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "<extract key terms from user's question>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 10
   ```

   Pass the commercetools project key and region (as in `api.{region}.commercetools.com`) only if already in your context; otherwise omit both. Never search files or ask the user for them.
   <!-- ct:docs-search:end -->

2. **Combine with skill references** — Cross-reference the analysis output with local references in `./references/` for complete context.

3. **Provide implementation guidance** — Synthesize the documentation with the specific integration mode the user is targeting.

### Optional scripts

**Fetch GraphQL schema** — Run this when you need context about a commercetools GraphQL query or mutation — for example, to inspect a resource's fields, types, and available operations before writing a query, or to verify a GraphQL query/mutation you have just generated against the real schema. It fetches the partial GraphQL SDL for a single commercetools resource:
  ```bash
  node scripts/graphql-schemata.mjs \
    --resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
    --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
    --model "<current-model>"
  ```
  The output is the GraphQL SDL for that resource. If the resource name is not recognized, the script prints the list of valid 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 30 — file references are metadata, not package contents.

View saved version →

---
name: commercetools-connect
description: "Build, test, deploy, and certify commercetools Connect applications — service/API-extension, event/subscription, job, and Connect-hosted Merchant Center custom apps and views — in TypeScript/JavaScript (Java supported). Covers the connect.yaml contract, least-privilege scopes, lifecycle scripts, sync-vs-async idempotency and ack, testing, and deployment. For a named vendor or domain integration see commercetools-integrations; not for the hosted Checkout widget (see commercetools-checkout). Use when building, deploying, certifying, or debugging a Connect connector."
when_to_use:
  - "Building or debugging a Connect application: service/API-extension, event/subscription, job, or a Connect-deployed merchant-center custom application or custom view"
  - "Writing connect.yaml: standardConfiguration, securedConfiguration, inheritAs scopes, endpoint, properties.schedule"
  - "postDeploy/preUndeploy lifecycle scripts that register Extensions, Subscriptions, Custom Types, or Channels"
  - "Choosing an API Extension vs a Subscription; fixing idempotency, ack codes, redelivery, or a 202 response"
  - "Deploying, redeploying, or certifying a connector; sandbox vs preview vs production, regions"
  - "Testing a connector locally, or operating a deployed one: logs, correlation IDs, poison messages, DLQ replay"
  - "Syncing commercetools to or from an external system (ERP, OMS, PIM, CRM, tax, search) — see commercetools-integrations"
  - "Custom app missing from the Merchant Center nav, or hosting/installing one — see commercetools-custom-application"
  - "Implementing a spec/plan/tasks.md task annotated [SKILL: commercetools-connect]"
metadata:
  contentType: SKILL
  area:
    - Foundations
    - Integrations
  docsSearch:
    products:
      - Composable Commerce
      - Checkout
      - Connect
      - InStore
      - AI Hub
---

# commercetools Connect

Intent-driven guidance for building **production-ready** Connect applications. This skill teaches the decision frameworks, platform contracts, and best practices that survive a production-readiness review — not a single connector's code. It generalizes patterns (and warns against anti-patterns) found in real connectors, and grounds every platform fact in official docs.

**Language scope:** Connect applications can be written in **JavaScript/TypeScript or Java** ([docs](https://docs.commercetools.com/connect/development.md)); the `create-connect-app` template supports JS and TS. **This skill targets TypeScript/Node** — the decision frameworks, platform contracts (timeouts, ack semantics, scopes, lifecycle), and `connect.yaml` guidance are language-agnostic and apply equally to a Java connector, but the code snippets and the supertest + msw test stack are Node/Express-specific.

**Tooling — use the Connect CLI, don't hand-roll.** Scaffold, run, and ship with the official Connect CLI (`@commercetools/cli`). Every CLI command, the bootstrap flow, and the pinned dependency versions live in one place: the **Connect CLI** reference ([connect-cli.md](./references/connect-cli.md)). Merchant Center custom applications/views are the exception: they use a *separate* frontend toolchain (`@commercetools-frontend/*`) and only ride the Connect CLI at deploy time and directory structure — see [merchant-center-cli.md](./references/merchant-center-cli.md) and [merchant-center-customizations.md](./references/merchant-center-customizations.md).

## Workflow

When this skill is invoked, always follow these steps:

1. <!-- ct:docs-search:begin -->
   **Docs search (required, run first)** — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 17 — file references are metadata, not package contents.

View saved version →

---
name: commercetools-custom-application
description: "Create a Merchant Center Custom Application and get it into the main nav: asks for your details in chat, scaffolds the app in its own git repo, deploys it to a host such as Vercel, registers it, installs it in the Organizations you choose (all projects or an allowlist), and opens the app. Use when the user wants a custom app or nav item, or it only works on localhost. Not for Custom Views, or for Connect service, event and job connectors (see commercetools-connect)."
when_to_use:
  - "Creating a new Merchant Center Custom Application and getting it into the main nav of a Project"
  - "Registering, deploying, or installing an existing custom app built with create-mc-app"
  - "A custom app that works on localhost but is not showing up in the Merchant Center menu"
  - "Installing a custom app into several Organizations, all projects or a project allowlist for each"
metadata:
  contentType: SKILL
  area:
    - Foundations
  docsSearch:
    products:
      - Composable Commerce
---

# Merchant Center Custom Application, zero to nav

End state: a Custom Application on a static host, registered in the user's Organization, Ready, installed in every Organization the user chose (all projects, or an allowlist per Organization), and in those Projects' main menu.

Assumed: the user has a commercetools Project and is in the `Administrators` Team of an Organization. "Nothing configured" means no custom app yet, not no account. No Project: stop and say so.

## How this skill works

The procedure lives in `scripts/`, not here. Registration is a dozen order-dependent calls, and its failures (wrong `applicationId` in the build, URL mismatch, Draft state) show up far from their cause. So the scripts read the real Merchant Center state, pick the next step, and act. A rerun after any interruption resumes. Your job: gather inputs, run the scripts in order, and handle what scripts cannot: the email click and, with deployment help off, the deploy.

Every script prints JSON. Read `ok`, `error`, `stoppedAt`, and `checks[].detail`; never assume a step worked. Run them as `node <skill-dir>/scripts/<name>.mjs`.

The scripts carry the procedure; the Merchant Center facts around it (what an `entryPointUriPath` may be, which permissions a Team needs, what a host must do) come from the documentation, so:

1. <!-- ct:docs-search:begin -->
   **Docs search (required, run first)** — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the skill text alone:

   ```bash
   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "Merchant Center Custom Application <the user's situation: register, deploy, install, permissions, host>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 5
   ```

   Pass the commercetools project key and region (as in `api.{region}.commercetools.com`) only if already in your context; otherwise omit both. Never search files or ask the user for them.
   <!-- ct:docs-search:end -->

2. Then run Step 0. Headless is the only route, always, whether or not the user has a terminal. The manual steps are for redoing one piece by hand, or for when you cannot run commands.

## Step 0: run headless (the whole flow, from nothing)

Headless is the only route. You run `headless.mjs` and the user answers in chat, whether or not they have a terminal. Do not offer or run `onboard.mjs`. The protocol (exit codes, the plan file shape, what each step may ask for) is in [headles

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 100 — file references are metadata, not package contents.

View saved version →

---
name: commercetools-intake
description: "Integrate Intake over its stateless responses API so unstructured customer input (an email, support ticket, PDF, spreadsheet, CSV, or free text, including an inbound quote or purchase order) becomes one Cart, Quote Request, or Shopping List. Use when connecting that input to Intake (also called the Intake Agent), including outputType, file upload, and writing the created id back to the channel. Not the Merchant Center Intake UI, and not ongoing ERP, CRM, or transactional-email sync (see commercetools-integrations)."
when_to_use:
  - "An inbound purchase-order email should become a Cart or Quote Request through the Intake API"
  - "A Zendesk ticket, with its requester and attachments, should create a commercetools entity via POST /agents/intake/v1/responses"
  - "A retried Intake call created a second Cart, or a mailbox integration got BusinessUnitUnresolved or MissingCustomerEmail"
  - "Choosing Cart, Quote Request, or Shopping List for an unstructured order request"
metadata:
  contentType: SKILL
  area:
    - "Integrations"
  docsSearch:
    products:
      - AI Hub
      - Composable Commerce
---

# Intake

Call [Intake](https://docs.commercetools.com/api/projects/intake.md) so a channel adapter can turn one unstructured request into one commercetools entity. The HTTP surface is a single stateless endpoint. Each call starts a fresh run and returns either a created entity or an error. It does not resume a previous run, so a follow-up email or ticket comment is not another turn of the same call.

The adapter owns three decisions Intake will not make: which entity to create, which Customer the message is for, and whether this inbound event is a new request or a reply to an entity already created.

## Out of scope

- Building or automating the [Merchant Center](https://docs.commercetools.com/merchant-center/ai-agents/intake.md) Intake UI. Use that UI once, before writing the adapter, to confirm the same prompt creates the entity. The UI can ask a clarifying question. This endpoint cannot.
- Connect connectors, transactional email, and CRM sync. Those belong to [commercetools-integrations](../commercetools-integrations/SKILL.md).
- Quote negotiation after a Quote Request exists (Staged Quote, Quote, Order). That is the [Quotes API](https://docs.commercetools.com/api/quotes-overview.md).

## Workflow

1. <!-- ct:docs-search:begin -->
   **Docs search (required, run first)** — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the skill text alone:

   ```bash
   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "Intake responses API Cart Quote Request Shopping List file upload" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 10
   ```

   Pass the commercetools project key and region (as in `api.{region}.commercetools.com`) only if already in your context; otherwise omit both. Never search files or ask the user for them.
   <!-- ct:docs-search:end -->

2. **Fetch the REST schema** before writing a request or parsing a response. Run:

   ```bash
   node scripts/openApi-schemata.mjs \
     --resource-name "api-AgentResponsesSuccess" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>"
   ```

   The output is the OpenAPI specification for that resource. If the name is not recognized, the script prints valid names. Re-run with `api-Cart-write`, `api-QuoteRequest`, or 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: commercetools-integration-layer
description: "Build and publish extensions for the commercetools Commerce Integration Layer — the project-scoped commercetools BFF. Covers the two extension types (a schema extension, i.e. an extension subgraph of GraphQL typeDefs + resolvers that shapes what clients read through the Experience API; and a Managed API Extension that approves, modifies, or blocks a commercetools write), a decision tree for where custom logic belongs (incl. porting pre-request BFF logic), and the integration-layer CLI flow to init, test, validate, and push an extension bundle. Use when building, publishing, or debugging a Commerce Integration Layer extension, or asking how to add custom logic to a Commerce Integration Layer project — even if the user just says 'integration layer' or 'CIL'. Not for building commercetools Connect connectors (see commercetools-connect), the hosted Checkout (see commercetools-checkout), or storefront clients that consume the Experience API (see commercetools-storefront)."
when_to_use:
  - "Building or publishing an extension for the commercetools Commerce Integration Layer"
  - "Deciding between a schema extension and a Managed API Extension for a Commerce Integration Layer project"
  - "Porting BFF logic that derived or enriched a request before it reached commercetools into a Commerce Integration Layer project"
  - "Using the integration-layer CLI to init, run, validate, or push an extension bundle"
  - "Testing a Commerce Integration Layer bundle (schema extensions and API Extension handlers) before pushing it"
metadata:
  contentType: SKILL
  area:
    - "Integrations"
---

# commercetools Commerce Integration Layer

The Commerce Integration Layer is a project-scoped commercetools BFF: a GraphQL
edge in front of a commercetools Project that storefronts and other clients read through
the **Experience API**. You extend it with **extension bundles** you author, validate,
and publish yourself.

This skill covers **building extensions** for the Commerce Integration Layer. It is not about consuming the Experience API
from a storefront, and it is not about commercetools Connect connectors — those are
different mechanisms with their own skills.

> The [Commerce Integration Layer documentation](https://docs.commercetools.com/commerce-integration-layer.md)
> is the source of truth: [Get started](https://docs.commercetools.com/commerce-integration-layer/development/get-started.md),
> [Choose an extension type](https://docs.commercetools.com/commerce-integration-layer/extension-types.md),
> [Write schema extensions](https://docs.commercetools.com/commerce-integration-layer/development/writing-schema-extensions.md),
> [Write Managed API Extensions](https://docs.commercetools.com/commerce-integration-layer/development/writing-managed-api-extensions.md),
> [Configure and deploy](https://docs.commercetools.com/commerce-integration-layer/development/configure-and-deploy.md),
> and, when replacing a hand-built BFF, [Migrate an existing BFF](https://docs.commercetools.com/guides/migration-guides/migrate-existing-bff.md).
> The [`commerce-integration-layer-extensions`](https://github.com/commercetools/commerce-integration-layer-extensions)
> repository holds runnable example extensions to start from.

## Where the logic must run

Choose the mechanism from *when in an API call* the logic must run, not from how it feels
to write. The Commerce Integration Layer sits on every client flow, so each moment below has a home:

| Moment | Mechanism |
| :--- | :--- |
| A client **reads** data | **Schema extension** |
| **Before** commercetools processes a write (deriving or enriching the input) | Usually still a **Managed API Extension**. See [the write path](references/write-path.md) |
| **Within** a write, before it is persisted (approve, modify, block) | **Managed API Extension** |
| **After** a write is persisted | commercetools **Subscription**, outside the bundle |

### Decision tree

Work top-do

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: commercetools-integrations
description: "Integrate commercetools with an external system through Connect. Thirteen domain sub-areas each start at a native-capability gate, then pick a rung: use a public connector, close the gap with config, fork one, or build new. Build contracts live in commercetools-connect. Use when syncing commercetools to or from an external system, or debugging a deployed connector. Not for turning unstructured inbound sales input (a quote, purchase order, email, ticket, PDF, or spreadsheet) into one Cart, Quote Request, or Shopping List (see commercetools-intake)."
when_to_use:
  - "Payment (Stripe, Adyen, Mollie, PayPal) and gift card (Voucherify) connectors: payment session, capture/refund, redeem"
  - "Tax connectors (Avalara, Vertex, TaxJar): calculator API Extension, ExternalAmount, taxedPrice missing"
  - "ERP (SAP, Dynamics, NetSuite, Odoo) or OMS (Fluent, fulfillmenttools): OrderCreated export, SyncInfo, stock drift"
  - "PIM (Akeneo) or CRM (Salesforce, HubSpot, Dynamics, Zoho) sync: externalId linking, Import API vs HTTP API, sync loops"
  - "Search (Algolia, Constructor, Bloomreach) or analytics export (BigQuery, Snowflake, Segment): reindex, lastModifiedAt job"
  - "Shipping (carriers, rate engines, labels): setShippingRateInput vs setCustomShippingMethod"
  - "Promotion/loyalty (Talon.One, Voucherify, Eagle Eye): setDirectDiscounts, inert Discount Codes"
  - "Marketplace (Mirakl, Marketplacer, channel managers): sellers, offers, per-seller prices"
  - "Transactional email (SendGrid, Mailgun, AWS SES): at-most-once vs at-least-once, no emails sent"
  - "Implementing a spec/plan/tasks.md task annotated [SKILL: commercetools-integrations]"
metadata:
  contentType: SKILL
  area:
    - Integrations
  docsSearch:
    products:
      - Composable Commerce
      - Checkout
      - Connect
      - InStore
      - AI Hub
---

# commercetools integrations

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

**This skill is the canonical home of all thirteen sub-area trees.** They live here and nowhere else: [commercetools-connect](../commercetools-connect/SKILL.md) links into them rather than carrying a copy, so add or edit a sub-area here only.

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

## Route to the sub-area first

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

| Domain | Sub-area |
|---|---|
| **Payment** (Stripe, Adyen, Mollie, PayPal, …) | [references/payment/overview.md](./references/payment/overview.md) |
| **Tax** (Avalara, Vertex, TaxJar, …) | [references/tax/overview.md](./references/tax/overview.md) |
| **CRM** (Salesforce, HubSpot, Dynamics 365, Zoho, …) | [references/crm/overview.md](./references/crm/overview.md) |
| **PIM** (Akeneo, inriver, Bluestone, Pimcore, …) | [references/pim/overview.md](./references/pim/overview.md) |
| **Order management / OMS** (Fluent Commerce, fulfillmenttools, kbrw, OneStock, NewStore, Pipe17) | [references/order-management/overview.md](./references/order-management/overview.md) |
| **ERP** (SAP S/4HANA or ECC, Microsoft Dynamics 365, Oracle NetSuite, Infor, Odoo, Sage, …) | [references/erp/overview.md](./ref

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 80 — file references are metadata, not package contents.

View saved version →

---
name: commercetools-mcp
description: "Connect a coding agent to commercetools Projects through managed Commerce MCP Servers with Merchant Center sign-in, configured per repository, and design focused Commerce MCP Servers for other agents: minimal tools, filtered responses, task-specific descriptions, validated with blind agent runs. Points to the documentation for the Knowledge MCP. Use when connecting a coding agent to a commercetools Project, continuing that setup after sign-in, or giving an agent only the Commerce MCP tools and data its task needs."
when_to_use:
  - "Connecting a coding agent to a commercetools Project, or adding another Project to a repository"
  - "Continuing a commercetools MCP setup after sign-in"
  - "Building a Commerce MCP surface for a specific agent: least-privilege tools, smaller responses, redacted fields"
  - "Creating or updating a Managed MCP Server, or emitting a self-hosted commerce-mcp config, for an agent"
  - "Asked where to start with managed or self-hosted Commerce MCP, or with the Knowledge MCP"
metadata:
  contentType: SKILL
  area:
    - Foundations
  docsSearch:
    products:
      - Composable Commerce
---

# commercetools MCP

| Server | Gives an agent | Access |
| :----- | :------------- | :----- |
| [Knowledge MCP](https://docs.commercetools.com/dev-tooling/mcp/knowledge-mcp.md) | Documentation search, GraphQL and OpenAPI schemas, query validation | Public, no sign-in. Bundled with this plugin. |
| [Commerce MCP](https://docs.commercetools.com/dev-tooling/mcp/commerce-mcp.md) | Tools that read and change Project data | Needs access to a Project. Managed (hosted by commercetools, configured in the Merchant Center) or self-hosted (you run the open-source package). |

## Connect your development environment

For a coding agent that reads and configures a Project while you build a solution, follow
[Repository connection](./references/repository-connection.md). Each developer signs in with their
Merchant Center account through a managed MCP Server, and the connection is shared through the
repository.

## Configure an MCP server for an agent

For an agent with one job, such as a support assistant or a promotion agent, follow
[Agent MCP server](./references/agent-server.md). It cuts the Commerce MCP down to the tools and fields
the task needs, sharpens tool descriptions and parameters, creates the managed MCP Server (or emits a
self-hosted configuration), and tests it with blind agent runs. The design work itself runs through the
repository connection.

## Other uses

Answer other Commerce MCP and Knowledge MCP questions from the documentation:

- [Managed MCP Servers overview](https://docs.commercetools.com/api/managed-mcp-servers-overview.md)
- [Self-hosted Commerce MCP](https://docs.commercetools.com/dev-tooling/mcp/self-hosted-commerce-mcp.md)
- Knowledge MCP: [recommended workflows](https://docs.commercetools.com/dev-tooling/mcp/knowledge-mcp.md#recommended-workflows)

## Checklist

- [ ] Development-environment connections follow the repository connection
- [ ] MCP servers for other agents follow the agent MCP server workflow, including its blind runs
- [ ] Other Commerce MCP and Knowledge MCP questions answered from the linked documentation

Referenced files: 15 — file references are metadata, not package contents.

View saved version →

---
name: commercetools-openai-setup
description: "Setup for the commercetools plugin in ChatGPT and Codex: checks whether a commercetools Project is already connected, and explains the optional ways to connect one, as a custom MCP server in ChatGPT or a per-repository connection in a coding agent. Use when the plugin's setup runs after installation, or when asked to set up commercetools or connect a commercetools Project in ChatGPT or Codex."
when_to_use:
  - "The commercetools plugin's setup was started in ChatGPT or Codex"
  - "Asked to set up commercetools, or to connect a commercetools Project, in ChatGPT or Codex"
metadata:
  contentType: SKILL
  area:
    - Foundations
---

# commercetools setup for ChatGPT and Codex

The plugin is ready to use as installed: it brings the commercetools skills and access to the
commercetools documentation and API reference. Connecting a commercetools Project is optional. It
lets the agent read and change that Project's data, through a managed MCP server in the Merchant
Center.

Don't change settings or configuration yourself, and don't search the filesystem. Explain, let the
user choose, and give the steps for their choice only.

## 1. Check for a connection

If a tool from a commercetools MCP server, such as `read_project`, is available, call it and
report:

> Connected to `{projectKey}`: `{project display name}`. You're set up.

Then stop. Otherwise continue with step 2.

## 2. Explain the options

Tell the user:

> commercetools is ready: you can ask about commercetools and build with it now. To also let me
> work with your Project's data, you can connect a Project:
>
> 1. **In ChatGPT conversations:** add the Project's managed MCP server as a custom MCP server.
> 2. **In a code repository** (for example in Codex): connect the Project to that repository, so
>    your team shares the connection.
>
> Or skip this: nothing else needs setting up. That's also the choice if your ChatGPT workspace
> admin sets up plugins for you: they provide the connection.
>
> What would you like to do?

If the user skips, or their admin sets things up, confirm that the plugin works as it is, and stop.

## 3a. ChatGPT conversations

> Create a managed MCP server for your Project in the Merchant Center, then add its URL in ChatGPT
> as a custom MCP server (**Plugins → Add → Add custom MCP server**). See
> [managed MCP servers](https://docs.commercetools.com/merchant-center/managed-mcp-servers.md).

## 3b. Code repository

Continue with the `commercetools-mcp` skill, Repository connection. It needs a code repository open
in the agent. If none is open, say so and stop.

## Checklist

- [ ] An existing connection reported, without offering more
- [ ] Connecting presented as optional, with both options and the choice to skip (or leave it to the admin)
- [ ] Only the chosen option's steps given; nothing configured on the user's behalf

View saved version →

---
name: commercetools-platform
description: Core commercetools API and SDK patterns — TypeScript SDK setup, ClientBuilder authentication, project data model (products, customers, orders, types, channels, stores), GraphQL vs REST patterns, query predicates, optimistic concurrency, rate limits, and platform observability. Foundational layer that storefront, MC app, Connect, and integration skills all reference. Use for any commercetools project regardless of surface.
when_to_use:
  - "Setting up a new commercetools project in TypeScript"
  - "Connecting to the commercetools API from any surface (storefront, MC app, Connect, serverless function)"
  - "Implementing product search with the Product Search API"
  - "Implementing a spec/plan/tasks.md task annotated [SKILL: commercetools-platform]"
  - "An implementation-plan step that sets up commercetools SDK clients, auth, or API access"
metadata:
  contentType: SKILL
  area:
    - Foundations
  docsSearch:
    products:
      - Composable Commerce
      - Checkout
      - Connect
      - InStore
      - AI Hub
---

# commercetools TypeScript SDK

Foundational patterns for connecting to the commercetools API from TypeScript. These patterns are project-type agnostic — they apply whether you are building a Next.js storefront, a serverless function, or a CLI script.

## Workflow

When this skill is invoked, always follow these steps:

1. <!-- ct:docs-search:begin -->
   **Docs search (required, run first)** — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the skill text alone:

   ```bash
   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "<extract key terms from user's question>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 10
   ```

   Pass the commercetools project key and region (as in `api.{region}.commercetools.com`) only if already in your context; otherwise omit both. Never search files or ask the user for them.
   <!-- ct:docs-search:end -->

2. **Combine with skill references** — Cross-reference the analysis output with local references in `./references/` for complete context.

3. **Provide implementation guidance** — Synthesize the documentation with the specific integration mode the user is targeting.

### Optional scripts

**Fetch GraphQL schema** — Run this when you need context about a commercetools GraphQL query or mutation — for example, to inspect a resource's fields, types, and available operations before writing a query, or to verify a GraphQL query/mutation you have just generated against the real schema. It fetches the partial GraphQL SDL for a single commercetools resource:
   ```bash
   node scripts/graphql-schemata.mjs \
     --resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>"
   ```
   The output is the GraphQL SDL for that resource. If the resource name is not recognized, the script prints the list of valid resource names — pick the correct one and re-run. **Note:** the SDL may contain *stubbed types* — referenced resources rendered as stubs, with their real type name given in a comment. Fetch any you need separately by re-running this script with that type name as `--resource-name`.

**Fetch OpenAPI (REST) schema** — Run this when you need context about a commercetools REST endpoint, request/response payload, or update action — for example, to inspect a re

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: commercetools-spec-driven-development
description: Wire the commercetools skills into a spec-driven development framework — GitHub Spec Kit (.specify/), OpenSpec (openspec/), or BMad Method (_bmad/). Use when user wants to set up or check the status of a spec-driven development framework that touches commercetools.
when_to_use:
  - "Setting up GitHub Spec Kit, OpenSpec, or the BMad Method in a project that touches commercetools, or wiring commercetools into an existing one"
  - "Checking the status of, or removing, the commercetools spec-driven-development overlay"
metadata:
  contentType: SKILL
  area:
    - Foundations
  docsSearch:
    products:
      - Composable Commerce
      - Checkout
      - Connect
      - InStore
      - AI Hub
---

# commercetools Spec-Driven Development Overlay

Makes a spec-driven development framework commercetools-aware, so every spec, plan, and task that touches commercetools loads the matching `commercetools-*` skill first. The framework keeps owning the workflow — this only adds commercetools rules through the surface each framework already offers for that.

| Detected directory | Framework | How the overlay applies |
| :--- | :--- | :--- |
| `.specify/` | GitHub Spec Kit | Marker-fenced blocks in files it already has; creates no files |
| `openspec/` | OpenSpec | Marker-fenced blocks in files it already has; creates no files |
| `_bmad/` | BMad Method | Sparse override files in `_bmad/custom/`, the directory BMad contracts for this |

Any combination present means each detected framework gets the overlay. BMad never has its installed files edited: it regenerates them on every install, so patching them would be destructive.

## Workflow

1. <!-- ct:docs-search:begin -->
   **Docs search (required, run first)** — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the skill text alone:

   ```bash
   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "<extract key terms from the user's question>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 10
   ```

   Pass the commercetools project key and region (as in `api.{region}.commercetools.com`) only if already in your context; otherwise omit both. Never search files or ask the user for them.
   <!-- ct:docs-search:end -->

   Query the commercetools areas the project targets, not the framework's own terminology — those results are what let you fill in the plan's "Platform Skills Resolution" table later. This script queries the same index as the commercetools Knowledge MCP, with the product filters this skill needs — use it rather than the MCP tool while working in this skill.

2. **Run the setup script (required, do the work with this)** — never hand-edit the framework's files to apply the overlay; the script is idempotent and reversible, hand edits are neither:

   ```bash
   node scripts/setup.mjs
   ```

   | Argument | Effect |
   | :--- | :--- |
   | *(none)* or `init` | Apply the overlay to every detected framework |
   | `status` | Report what is applied; writes nothing |
   | `remove` | Strip applied blocks and delete files the overlay wrote |
   | `--dry-run` | Preview `init`/`remove` without writing |
   | `--framework speckit\|openspec\|bmad` | Act on one framework only |
   | `--cwd <dir>` | Target a project other than the current directory |

3. **Report what the script printed**, and handle these outcomes:

   - **No framework detected** (exit 4) — tell the user to run `specify init` (S

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 15 — file references are metadata, not package contents.

View saved version →

---
name: commercetools-storefront
description: Production patterns for building customer-facing storefronts on commercetools - the full B2C and B2B domain feature set. Patterns are stated as decisions plus commercetools-exact code; framework-specific implementation. Assumes a server tier exists to host the BFF. Use for PDP, PLP, cart, checkout flow, customer login, search/facets, locale handling, and any B2B- or B2C-specific feature.
when_to_use:
  - "Implementing a commercetools storefront (BFF, sessions, carts, checkout, B2C/B2B features) regardless of frontend framework"
  - "Adding a new feature to an existing commercetools storefront"
  - "Building a B2C storefront: anonymous carts, customer auth, BOPIS, bundles, promotions, or CSR impersonation"
  - "Building a B2B storefront: quotes, approval workflows, store-scoped pricing, purchase lists, or recurring orders"
  - "Deciding server-rendered vs client-fetched data loading, designing the commercetools type boundary, or the as-associate API chain"
  - "Implementing a spec/plan/tasks.md task annotated [SKILL: commercetools-storefront]"
  - "An implementation-plan step that builds a storefront surface (PDP/PLP/cart/customer/B2B)"
metadata:
  contentType: SKILL
  area:
    - Foundations
  docsSearch:
    products:
      - Composable Commerce
      - Checkout
      - Connect
      - AI Hub
---

# commercetools Storefront (framework-agnostic)

Production patterns for commercetools storefronts — covering the full range from the shared BFF foundation to B2C and B2B surface-specific features. The patterns here are framework-neutral: each is stated as a decision plus commercetools-exact code. Your frontend framework supplies the implementation primitives (file layout, render and routing primitives, the cookie read/write binding).

> **Architecture assumption — a server tier exists.** These patterns assume your storefront runs on a stack with a server-side tier (SSR / server components / a standalone BFF service) that can hold secrets and proxy commercetools. The BFF and secret rules below are non-negotiable and depend on this. They are designed SSR-first. For a specific framework, use its stack adapter under `references/stack/` — e.g. the **[Next.js stack](./references/stack/nextjs/overview.md)** — which maps each concept here to that framework's primitives and owns all file-layout and render-primitive details.

> **Reference implementation.** Where a code example shows a file path or a render primitive, it uses the Next.js App Router as the reference implementation. The framework-neutral rule is always in the surrounding prose; the adapter pins the exact primitive.

**Path & state conventions.**

Each reference implementation follows these conventions for paths and state management. The conventions are not technically required, but they are widely used in production storefronts and make it easier to navigate the codebase and onboard new developers. Find the `concept-mapping.md` in your stack adapter for the exact primitives used.
> | Convention | Meaning |
> | --- | --- |
> | `<server>/` | Your server-side code root; each stack pins the actual directory (Example Next.js: `lib/`) |
> | `<api>/` | the client-facing API surface the browser calls and routes |
> | `<server>/ct/*` | The commercetools helper modules |
> | `<server>/ct/client` | The `apiRoot` singleton |
> | `<server>/types` | The app type-mapping root (the boundary types) |
> | `<server>/mappers/` | The commercetools→app mappers |
> | **Client state** | Your framework's client-side state-management / cache layer (the specific library is a stack choice) — use it for mutable per-user data |

## Workflow

When this skill is invoked, always follow these steps:

1. <!-- ct:docs-search:begin -->
   **Docs search (required, run first)** — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 68 — file references are metadata, not package contents.