{"id":87256,"plugin_id":"plugin_asdk_app_6accac05de5c81919f8f192011f3a125","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-09T12:08:01.891Z","digest":"5246153ab36d4541e2e93dbf731a018056e510d4fc3c18c6e11019db403558ed","against":null,"payload":{"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).","included_files":[{"relative_path":"references/verify-and-push.md","size_in_bytes":12702},{"relative_path":"references/write-path.md","size_in_bytes":5493}],"name":"commercetools-integration-layer","skill_md_contents":"---\nname: commercetools-integration-layer\ndescription: \"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).\"\nwhen_to_use:\n  - \"Building or publishing an extension for the commercetools Commerce Integration Layer\"\n  - \"Deciding between a schema extension and a Managed API Extension for a Commerce Integration Layer project\"\n  - \"Porting BFF logic that derived or enriched a request before it reached commercetools into a Commerce Integration Layer project\"\n  - \"Using the integration-layer CLI to init, run, validate, or push an extension bundle\"\n  - \"Testing a Commerce Integration Layer bundle (schema extensions and API Extension handlers) before pushing it\"\nmetadata:\n  contentType: SKILL\n  area:\n    - \"Integrations\"\n---\n\n# commercetools Commerce Integration Layer\n\nThe Commerce Integration Layer is a project-scoped commercetools BFF: a GraphQL\nedge in front of a commercetools Project that storefronts and other clients read through\nthe **Experience API**. You extend it with **extension bundles** you author, validate,\nand publish yourself.\n\nThis skill covers **building extensions** for the Commerce Integration Layer. It is not about consuming the Experience API\nfrom a storefront, and it is not about commercetools Connect connectors — those are\ndifferent mechanisms with their own skills.\n\n> The [Commerce Integration Layer documentation](https://docs.commercetools.com/commerce-integration-layer.md)\n> is the source of truth: [Get started](https://docs.commercetools.com/commerce-integration-layer/development/get-started.md),\n> [Choose an extension type](https://docs.commercetools.com/commerce-integration-layer/extension-types.md),\n> [Write schema extensions](https://docs.commercetools.com/commerce-integration-layer/development/writing-schema-extensions.md),\n> [Write Managed API Extensions](https://docs.commercetools.com/commerce-integration-layer/development/writing-managed-api-extensions.md),\n> [Configure and deploy](https://docs.commercetools.com/commerce-integration-layer/development/configure-and-deploy.md),\n> and, when replacing a hand-built BFF, [Migrate an existing BFF](https://docs.commercetools.com/guides/migration-guides/migrate-existing-bff.md).\n> The [`commerce-integration-layer-extensions`](https://github.com/commercetools/commerce-integration-layer-extensions)\n> repository holds runnable example extensions to start from.\n\n## Where the logic must run\n\nChoose the mechanism from *when in an API call* the logic must run, not from how it feels\nto write. The Commerce Integration Layer sits on every client flow, so each moment below has a home:\n\n| Moment | Mechanism |\n| :--- | :--- |\n| A client **reads** data | **Schema extension** |\n| **Before** commercetools processes a write (deriving or enriching the input) | Usually still a **Managed API Extension**. See [the write path](references/write-path.md) |\n| **Within** a write, before it is persisted (approve, modify, block) | **Managed API Extension** |\n| **After** a write is persisted | commercetools **Subscription**, outside the bundle |\n\n### Decision tree\n\nWork top-down and stop at the first step that fits:\n\n1. **Can built-in commercetools features model it?** Check data modeling and native\n   features first. The requirement often disappears, and nothing is cheaper to run.\n2. **Is it about what a client reads?** Use a **schema extension**.\n3. **Does it change how a commercetools write behaves?** Start with a **Managed API\n   Extension**, even if the old BFF did it before the request. If an API Extension cannot\n   solve it, reach out to commercetools support with the use case. As a final step,\n   override the existing mutation with `@override`. Read\n   [the write path](references/write-path.md) before going past the API Extension.\n4. **Is it a write to an external service provider?** Add a **custom mutation** on the\n   extension subgraph. This is the best way to go for that case.\n\nWhatever you build, key it to the **business action** (\"a line item is added to a\ncart\"), and cover every entry point: cart creation with line items, `addLineItem`, adding\na Shopping List. A handler for one update action leaves the other paths open.\n\n### Schema extension (an extension subgraph)\n\nGraphQL `typeDefs` + `resolvers` that federate into the Experience API. Use it to add a query,\ntype, or field on an entity (e.g. `Product`); to compute a value from data the Commerce Integration Layer owns\nor from fields your extensions expose (via `@requires`); to call an external service and\nreturn the result in the graph; or to shape and enrich what a storefront reads. For a\nwrite to an external service provider, a custom mutation on your subgraph is the best way\nto go. To change a commercetools write, start with a Managed API Extension instead.\n\nIt runs **at the edge**, so it only affects traffic that goes through the Experience API. It is not\na platform-wide guarantee.\n\n### Managed API Extension\n\nApproves, modifies, or blocks a commercetools write **before it is persisted**. Use it to\nenforce a rule on a cart, order, or customer and reject a bad write; to stamp, derive, or\ncorrect a field as part of the write; or whenever the rule must hold for *every* write\nregardless of which client made it (storefront, Merchant Center, direct API client). It\nbuilds on the commercetools [API Extensions](https://docs.commercetools.com/api/projects/api-extensions)\nmechanism, but the Commerce Integration Layer hosts and registers the handler for you.\n\nBecause it runs inside the write, it applies to **all consumers**: the platform-wide\nguarantee a schema extension cannot give.\n\n## Building an extension\n\nA Project must be [enrolled and activated](https://docs.commercetools.com/commerce-integration-layer/overview.md#enrollment)\nfor the Commerce Integration Layer before extensions can be published. The flow, from the\n[Get started](https://docs.commercetools.com/commerce-integration-layer/development/get-started.md) guide;\nthe `commerce-integration-layer-extensions` repo holds standalone example extensions, one per pattern.\n\nAsk the user before installing anything and before every push: the first two commands install\nthe CLI and its plugin on the user's machine, and `pnpm push` replaces what the Project serves.\nName the command and the target Project, and wait for an explicit yes. The user signs in themselves.\n\n```bash\n# Install the CLI and the integration-layer topic (once), then log in\nnpm install -g @commercetools/cli\ncommercetools plugins install @commercetools/cli-topic-integration-layer\ncommercetools auth login --project-key <your-project-key>\n\n# Start a real workspace (extensions merge into the one bundle a Project deploys)\ncommercetools integration-layer init\n\n# Or start from the template closest to what you want, then edit src/extension.ts\npnpm test         # unit tests for resolvers and handlers; offline\npnpm dev          # local gateway over the merged bundle + deployed Experience API; hot-reloads\npnpm validate     # sandbox, shape, composition, and breaking-change checks; no upload\npnpm push         # validates, replaces the Project's bundle, waits until it is running\n```\n\nBefore pushing, test the whole merged bundle in layers, including API Extension handlers\nfired offline and against real writes: see [verify and push](references/verify-and-push.md).\n\nA bundle may export schema extensions (`typeDefs` + `resolvers`), Managed API Extensions\n(`apiExtensions`), or both.\n\n## Workflow\n\n1. **Confirm the mechanism.** Walk the [decision tree](#decision-tree) with the user's\n   actual requirement. Don't skip its first step (native modeling), because a data-model\n   change often beats any extension. For anything past a Managed API\n   Extension, read [the write path](references/write-path.md).\n2. **Read before writing.** Open the Commerce Integration Layer documentation for the chosen type\n   ([schema extensions](https://docs.commercetools.com/commerce-integration-layer/development/writing-schema-extensions.md)\n   or [Managed API Extensions](https://docs.commercetools.com/commerce-integration-layer/development/writing-managed-api-extensions.md)),\n   then the closest example in the\n   [`commerce-integration-layer-extensions`](https://github.com/commercetools/commerce-integration-layer-extensions) repo.\n3. **Start from a template or `integration-layer init`.** Edit `src/extension.ts`; keep\n   one concern per extension so it merges cleanly into the Project bundle.\n4. **Test the merged bundle, validate, then push.** Follow\n   [verify and push](references/verify-and-push.md): unit tests, handlers fired offline,\n   the composed schema, and real writes for every entry point of the business action.\n   Then `pnpm validate`, and `pnpm push`, which only counts as done once it reports the\n   new revision as running.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}