Update to commercetools

{
  "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).",
  "included_files": [
    {
      "relative_path": "references/analytics/config-from-requirements.md",
      "size_in_bytes": 7994
    },
    {
      "relative_path": "references/analytics/connector-selection.md",
      "size_in_bytes": 6784
    },
    {
      "relative_path": "references/analytics/destinations.md",
      "size_in_bytes": 5830
    },
    {
      "relative_path": "references/analytics/overview.md",
      "size_in_bytes": 17800
    },
    {
      "relative_path": "references/analytics/pipeline-architecture.md",
      "size_in_bytes": 13072
    },
    {
      "relative_path": "references/analytics/verification.md",
      "size_in_bytes": 5136
    },
    {
      "relative_path": "references/crm/config-from-requirements.md",
      "size_in_bytes": 8230
    },
    {
      "relative_path": "references/crm/connector-selection.md",
      "size_in_bytes": 6809
    },
    {
      "relative_path": "references/crm/crm-contract.md",
      "size_in_bytes": 11231
    },
    {
      "relative_path": "references/crm/overview.md",
      "size_in_bytes": 18076
    },
    {
      "relative_path": "references/crm/verification.md",
      "size_in_bytes": 4003
    },
    {
      "relative_path": "references/email/config-from-requirements.md",
      "size_in_bytes": 8224
    },
    {
      "relative_path": "references/email/connector-selection.md",
      "size_in_bytes": 6900
    },
    {
      "relative_path": "references/email/email-contract.md",
      "size_in_bytes": 13795
    },
    {
      "relative_path": "references/email/overview.md",
      "size_in_bytes": 17439
    },
    {
      "relative_path": "references/email/providers.md",
      "size_in_bytes": 5126
    },
    {
      "relative_path": "references/email/verification.md",
      "size_in_bytes": 5071
    },
    {
      "relative_path": "references/erp/config-from-requirements.md",
      "size_in_bytes": 14430
    },
    {
      "relative_path": "references/erp/connector-selection.md",
      "size_in_bytes": 12054
    },
    {
      "relative_path": "references/erp/data-mapping.md",
      "size_in_bytes": 12429
    },
    {
      "relative_path": "references/erp/erp-contract.md",
      "size_in_bytes": 19665
    },
    {
      "relative_path": "references/erp/overview.md",
      "size_in_bytes": 22816
    },
    {
      "relative_path": "references/erp/verification.md",
      "size_in_bytes": 9837
    },
    {
      "relative_path": "references/giftcard/config-from-requirements.md",
      "size_in_bytes": 7366
    },
    {
      "relative_path": "references/giftcard/connector-selection.md",
      "size_in_bytes": 6750
    },
    {
      "relative_path": "references/giftcard/giftcard-contract.md",
      "size_in_bytes": 8836
    },
    {
      "relative_path": "references/giftcard/overview.md",
      "size_in_bytes": 17782
    },
    {
      "relative_path": "references/giftcard/verification.md",
      "size_in_bytes": 4494
    },
    {
      "relative_path": "references/marketplace/config-from-requirements.md",
      "size_in_bytes": 14295
    },
    {
      "relative_path": "references/marketplace/connector-selection.md",
      "size_in_bytes": 13189
    },
    {
      "relative_path": "references/marketplace/marketplace-contract.md",
      "size_in_bytes": 15232
    },
    {
      "relative_path": "references/marketplace/overview.md",
      "size_in_bytes": 17123
    },
    {
      "relative_path": "references/marketplace/verification.md",
      "size_in_bytes": 7441
    },
    {
      "relative_path": "references/order-management/build-oms-connector.md",
      "size_in_bytes": 7599
    },
    {
      "relative_path": "references/order-management/connector-selection.md",
      "size_in_bytes": 9795
    },
    {
      "relative_path": "references/order-management/overview.md",
      "size_in_bytes": 17421
    },
    {
      "relative_path": "references/order-management/sync-architecture.md",
      "size_in_bytes": 10407
    },
    {
      "relative_path": "references/payment/backend-integration.md",
      "size_in_bytes": 15561
    },
    {
      "relative_path": "references/payment/backend-tdd.md",
      "size_in_bytes": 19827
    },
    {
      "relative_path": "references/payment/config-from-requirements.md",
      "size_in_bytes": 14965
    },
    {
      "relative_path": "references/payment/connector-contract.md",
      "size_in_bytes": 22307
    },
    {
      "relative_path": "references/payment/connector-selection.md",
      "size_in_bytes": 8584
    },
    {
      "relative_path": "references/payment/deploy-custom-connector.md",
      "size_in_bytes": 16587
    },
    {
      "relative_path": "references/payment/deploy-public-connector.md",
      "size_in_bytes": 9064
    },
    {
      "relative_path": "references/payment/integration-test.md",
      "size_in_bytes": 10850
    },
    {
      "relative_path": "references/payment/overview.md",
      "size_in_bytes": 24561
    },
    {
      "relative_path": "references/payment/stripe.md",
      "size_in_bytes": 22448
    },
    {
      "relative_path": "references/payment/test-harness.md",
      "size_in_bytes": 8606
    },
    {
      "relative_path": "references/payment/verification.md",
      "size_in_bytes": 3590
    },
    {
      "relative_path": "references/pim/build-connector.md",
      "size_in_bytes": 10424
    },
    {
      "relative_path": "references/pim/connector-selection.md",
      "size_in_bytes": 13055
    },
    {
      "relative_path": "references/pim/data-mapping.md",
      "size_in_bytes": 12596
    },
    {
      "relative_path": "references/pim/overview.md",
      "size_in_bytes": 16252
    },
    {
      "relative_path": "references/pim/testing.md",
      "size_in_bytes": 11776
    },
    {
      "relative_path": "references/promotion/config-from-requirements.md",
      "size_in_bytes": 12739
    },
    {
      "relative_path": "references/promotion/connector-selection.md",
      "size_in_bytes": 11950
    },
    {
      "relative_path": "references/promotion/overview.md",
      "size_in_bytes": 19634
    },
    {
      "relative_path": "references/promotion/promotion-contract.md",
      "size_in_bytes": 16757
    },
    {
      "relative_path": "references/promotion/public-connectors.md",
      "size_in_bytes": 8981
    },
    {
      "relative_path": "references/promotion/verification.md",
      "size_in_bytes": 6870
    },
    {
      "relative_path": "references/search/config-from-requirements.md",
      "size_in_bytes": 9370
    },
    {
      "relative_path": "references/search/connector-selection.md",
      "size_in_bytes": 9666
    },
    {
      "relative_path": "references/search/data-mapping.md",
      "size_in_bytes": 12682
    },
    {
      "relative_path": "references/search/overview.md",
      "size_in_bytes": 14706
    },
    {
      "relative_path": "references/search/search-contract.md",
      "size_in_bytes": 11507
    },
    {
      "relative_path": "references/search/verification.md",
      "size_in_bytes": 6893
    },
    {
      "relative_path": "references/shipping/config-from-requirements.md",
      "size_in_bytes": 10130
    },
    {
      "relative_path": "references/shipping/connector-selection.md",
      "size_in_bytes": 10773
    },
    {
      "relative_path": "references/shipping/overview.md",
      "size_in_bytes": 19518
    },
    {
      "relative_path": "references/shipping/shipping-contract.md",
      "size_in_bytes": 17656
    },
    {
      "relative_path": "references/shipping/verification.md",
      "size_in_bytes": 7281
    },
    {
      "relative_path": "references/tax/avalara.md",
      "size_in_bytes": 9199
    },
    {
      "relative_path": "references/tax/config-from-requirements.md",
      "size_in_bytes": 7827
    },
    {
      "relative_path": "references/tax/connector-selection.md",
      "size_in_bytes": 6345
    },
    {
      "relative_path": "references/tax/overview.md",
      "size_in_bytes": 16899
    },
    {
      "relative_path": "references/tax/tax-contract.md",
      "size_in_bytes": 10276
    },
    {
      "relative_path": "references/tax/verification.md",
      "size_in_bytes": 4203
    },
    {
      "relative_path": "scripts/docs-search.mjs",
      "size_in_bytes": 26556
    },
    {
      "relative_path": "scripts/graphql-schemata.mjs",
      "size_in_bytes": 25248
    },
    {
      "relative_path": "scripts/openApi-schemata.mjs",
      "size_in_bytes": 25619
    }
  ],
  "name": "commercetools-integrations",
  "skill_md_contents": "---\nname: commercetools-integrations\ndescription: \"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).\"\nwhen_to_use:\n  - \"Payment (Stripe, Adyen, Mollie, PayPal) and gift card (Voucherify) connectors: payment session, capture/refund, redeem\"\n  - \"Tax connectors (Avalara, Vertex, TaxJar): calculator API Extension, ExternalAmount, taxedPrice missing\"\n  - \"ERP (SAP, Dynamics, NetSuite, Odoo) or OMS (Fluent, fulfillmenttools): OrderCreated export, SyncInfo, stock drift\"\n  - \"PIM (Akeneo) or CRM (Salesforce, HubSpot, Dynamics, Zoho) sync: externalId linking, Import API vs HTTP API, sync loops\"\n  - \"Search (Algolia, Constructor, Bloomreach) or analytics export (BigQuery, Snowflake, Segment): reindex, lastModifiedAt job\"\n  - \"Shipping (carriers, rate engines, labels): setShippingRateInput vs setCustomShippingMethod\"\n  - \"Promotion/loyalty (Talon.One, Voucherify, Eagle Eye): setDirectDiscounts, inert Discount Codes\"\n  - \"Marketplace (Mirakl, Marketplacer, channel managers): sellers, offers, per-seller prices\"\n  - \"Transactional email (SendGrid, Mailgun, AWS SES): at-most-once vs at-least-once, no emails sent\"\n  - \"Implementing a spec/plan/tasks.md task annotated [SKILL: commercetools-integrations]\"\nmetadata:\n  contentType: SKILL\n  area:\n    - Integrations\n  docsSearch:\n    products:\n      - Composable Commerce\n      - Checkout\n      - Connect\n      - InStore\n      - AI Hub\n---\n\n# commercetools integrations\n\nConnecting 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.\n\n**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.\n\n**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.\n\n## Route to the sub-area first\n\nDo 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.\n\n| Domain | Sub-area |\n|---|---|\n| **Payment** (Stripe, Adyen, Mollie, PayPal, …) | [references/payment/overview.md](./references/payment/overview.md) |\n| **Tax** (Avalara, Vertex, TaxJar, …) | [references/tax/overview.md](./references/tax/overview.md) |\n| **CRM** (Salesforce, HubSpot, Dynamics 365, Zoho, …) | [references/crm/overview.md](./references/crm/overview.md) |\n| **PIM** (Akeneo, inriver, Bluestone, Pimcore, …) | [references/pim/overview.md](./references/pim/overview.md) |\n| **Order management / OMS** (Fluent Commerce, fulfillmenttools, kbrw, OneStock, NewStore, Pipe17) | [references/order-management/overview.md](./references/order-management/overview.md) |\n| **ERP** (SAP S/4HANA or ECC, Microsoft Dynamics 365, Oracle NetSuite, Infor, Odoo, Sage, …) | [references/erp/overview.md](./references/erp/overview.md) |\n| **Gift card** (Voucherify, in-house store credit, …) | [references/giftcard/overview.md](./references/giftcard/overview.md) |\n| **Transactional email** (SendGrid, Mailgun, AWS SES, Postmark, …) | [references/email/overview.md](./references/email/overview.md) |\n| **Marketplace** (Marketplacer, Mirakl, Convictional, channel managers) | [references/marketplace/overview.md](./references/marketplace/overview.md) |\n| **Promotion / loyalty** (Talon.One, Voucherify, Dovetech, Eagle Eye, …) | [references/promotion/overview.md](./references/promotion/overview.md) |\n| **Analytics** — warehouse / CDP / product analytics (BigQuery, Snowflake, Redshift, Databricks, Segment, mParticle) | [references/analytics/overview.md](./references/analytics/overview.md) |\n| **Search / product discovery** (Algolia, Constructor, Bloomreach, Coveo, Elasticsearch, Typesense) | [references/search/overview.md](./references/search/overview.md) |\n| **Shipping** (carriers, rate-shopping engines, label/shipping-execution platforms) | [references/shipping/overview.md](./references/shipping/overview.md) |\n\nNot here: the hosted Checkout widget ([commercetools-checkout](../commercetools-checkout/SKILL.md)); surface-independent commerce domain logic such as pricing, discount stacking, tax modes, and native shipping modeling ([commercetools-commerce-patterns](../commercetools-commerce-patterns/SKILL.md)); SDK client setup, auth, and the core data model ([commercetools-platform](../commercetools-platform/SKILL.md)).\n\n## The ladder every sub-area walks\n\nThe rungs are the same across all thirteen; only the rung-0 native capability differs. Stop at the first rung that fits, and **present the choice to the user** — the rungs are materially different amounts of work.\n\n0. **Native commercetools capability** — does this need an integration at all? Real for promotion (Product Discounts / Cart Discounts / Discount Codes / Discount Groups), search (Product Search), and shipping (Zones, Shipping Methods, tiered rates, predicates). ERP has a variant of the same gate — does this data need replicating into commercetools at all, or read live? Rule it out explicitly, with the reason stated.\n1. **Use a public connector** — one exists and covers the requirements → install and configure. Check **live**, never from memory; name the connector and version you checked.\n2. **The gap is config, not code** — enabled features, credentials, markup, field mappings and fallback behavior are typically `connect.yaml` values → back to rung 1.\n3. **Customise / fork** — a real gap config can't close, and an open-source connector exists → fork, add only the delta, publish as an Organization connector.\n4. **Build a new one** — nothing exists for this vendor → build from the closest application template.\n\n**Verify a candidate is actually Connect-deployable before calling it installable.** A vendor listing is frequently the vendor's own hosted service plus glue you write — not something Connect deploys. The full rule, with the checks that settle it: [Marketplace listings are not all Connect connectors](../commercetools-connect/SKILL.md#marketplace-listings-are-not-all-connect-connectors--verify-before-recommending).\n\n<!-- ct:docs-search:begin -->\n### Step 0 — Gather context (run first)\n\nGather the latest verified documentation as your primary grounding for this sub-area. You must run this before designing anything here; the commercetools Knowledge MCP covers everything the script does not:\n\n```bash\nnode \"<this skill's directory>/scripts/docs-search.mjs\" \\\n  --query \"<terms from the user's request>\" \\\n  --app-name \"<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>\" \\\n  --model \"<current-model>\" \\\n  --commercetools-project-key \"<if known>\" \\\n  --commercetools-region \"<if known>\" \\\n  --limit 10\n```\n\nPass 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.\n<!-- ct:docs-search:end -->\n\nBoth scripts query the same index as the commercetools Knowledge MCP, with the product filters this skill needs — use them rather than the MCP tools while working in this skill. Run them from this skill's root. `scripts/openApi-schemata.mjs` and `scripts/graphql-schemata.mjs` are here too, for confirming request/response shapes from the OAS or GraphQL schema instead of from memory.\n\n## What a sub-area contains\n\nOnly `overview.md` and `connector-selection.md` exist everywhere. The rest is the common shape, not a guarantee — **list the sub-area's directory rather than assuming a file exists**:\n\n| File | Owns |\n|---|---|\n| `overview.md` | **Start here.** Present in all thirteen. Orientation, the rung-0 gate, requirements extraction, the workflow, and routing to the rest |\n| `connector-selection.md` | Present in all thirteen. The decision ladder for this domain: what exists, how to check live, which template to scaffold from |\n| `config-from-requirements.md` | Requirements → `connect.yaml`: applications, credentials, config keys, least-privilege scopes, worked example |\n| `*-contract.md` | The runtime contract: what each application must do, and the pitfall catalog |\n| `verification.md` | Proving the round trip works end to end, plus the traps that look like bugs |\n\nSub-areas name their files after what the domain actually needs, so several diverge: `pim/` uses `build-connector.md` + `data-mapping.md` + `testing.md`, `order-management/` uses `build-oms-connector.md` + `sync-architecture.md`, and `analytics/` uses `pipeline-architecture.md` — those three carry the runtime contract in place of a `*-contract.md`. `erp/` and `search/` carry a `*-contract.md` **and** a `data-mapping.md`, because in those two the field mapping is a decision set in its own right. Others add provider specifics, test harnesses, or public-connector assessments.\n\n## Rules that hold across all thirteen\n\n- **Ask, don't assume.** Requirements come before config, and config before code. Direction, source of truth, and what happens when the external system is down are business decisions — get them from the user and record them.\n- **Check the registry live.** Connector availability changes. One you remember may not exist; one you don't may.\n- **Vendor facts come from the vendor.** Their auth, payloads, field names, limits, and sandbox behavior are theirs to document and change — read their current API docs, and for a public connector its repo's `connect.yaml` and README. Do not write vendor field names from memory.\n- **Present the ladder; let the user choose the rung.** Give a recommendation and its reasoning, then record the decision.\n- **Hand back for the build.** Once the rung is chosen and the applications are designed, the lifecycle, testing, and production-readiness gate are [commercetools-connect](../commercetools-connect/SKILL.md).\n"
}