commercetools Platform SDK

The commercetools Platform SDK is the official TypeScript client for the commercetools Composable Commerce HTTP API. Rather than hand-writing HTTP calls, developers get a fluent, chainable request builder — apiRoot.withProjectKey(...).carts().withId(...).get().execute() — that mirrors the API’s resource tree one-to-one, with full request/response typings for carts, orders, products, customers, payments, subscriptions, and dozens of other resources.

The package is generated by commercetools’ own rmf-codegen tool directly from the platform’s RAML API definition, so the client stays in lockstep with the live API surface release after release — new endpoints and fields show up in the SDK automatically rather than through manual maintenance. It ships as a sibling package to @commercetools/ts-client, which handles the transport concerns (OAuth client-credentials flow, HTTP middleware, retries), keeping the platform-sdk package focused purely on typed request construction and response shapes.

It’s the backbone dependency for any Node.js or browser application integrating with commercetools — merchant back-office tools, custom storefronts, checkout flows, and internal automation that needs typed, autocomplete-friendly access to the full commerce API without hand-rolling REST calls.

What You Get

• A request builder for every platform resource (carts, orders, products, customers, payments, subscriptions, quotes, business units, and more), mirroring the REST path hierarchy exactly
• Generated TypeScript model types for every request and response shape, keeping application code in sync with the live API contract
• A thin createApiBuilderFromCtpClient entry point that wires the typed builders to a transport client from the companion @commercetools/ts-client package
• Dual-format distribution (CJS, ESM, and browser UMD bundles) so the same package works in Node.js services and browser bundles alike
• Automatic regeneration from commercetools’ RAML API spec on every platform release, so new endpoints and fields land in the SDK without manual porting

Common Use Cases

• Building custom storefronts or checkout flows that read and write carts, orders, and payments against a commercetools project
• Building merchant back-office tools and admin dashboards that manage products, inventory, and customer data
• Server-side integrations and middleware that sync commercetools data with ERPs, PIMs, or other commerce systems
• Scripted or automated bulk operations against a commercetools project (imports, migrations, data audits) with full type safety

Under The Hood

Architecture The package sits inside a Yarn-workspaces monorepo built with lerna, @manypkg/cli, and @preconstruct/cli, but its own architecture is a single generated layer: a thin hand-written entry point (src/ctp/ctp-client.ts) wraps an ApiRoot class from src/generated/index.ts, and everything beneath that is codegen output mirroring the commercetools REST resource tree one request-builder class per path segment (hundreds of files under src/generated/client/, e.g. by-project-key-carts-request-builder.ts). Each builder holds pathArgs and an injected executeRequest function, exposes methods that either descend further into the tree (.withId(), .carts()) or terminate into an ApiRequest from shared/utils/requests-utils that calls .execute(). There is no business logic beyond request construction — the transport implementation (auth, HTTP, retries) is injected from the separate @commercetools/ts-client package, so a change to that shared ApiRequest/executeRequest contract in shared/utils would ripple through effectively every generated file.

Tech Stack Written entirely in TypeScript (99.9% of the codebase) against a monorepo tooling stack of Yarn workspaces, lerna, @manypkg/cli for workspace consistency checks, and @preconstruct/cli to produce dual CJS/ESM output plus browser-specific UMD bundles via a custom esbuild postbuild step. Testing runs on Jest 30 with ts-jest and babel-jest; commit hygiene is enforced with husky, lint-staged, tsc-files, and commitlint; releases are versioned and changelogged through Changesets. The only runtime dependency is the sibling @commercetools/ts-client package, which supplies the OAuth client-credentials flow and HTTP middleware this SDK’s typed builders execute against. The package targets Node.js 22+ and is also distributed for direct <script>-tag browser use via unpkg.

Code Quality The generated client code is uniformly structured (every request-builder file follows the same constructor/method shape), which limits the surface for inconsistency even though most of it is machine-produced rather than hand-authored. Test coverage is comprehensive and unusually realistic for an SDK: alongside generated-client unit tests, the package ships 65+ integration test files under test/integration-tests/, organized per resource area (carts, orders, payments, customers, etc.), that exercise the SDK against a real commercetools project using required environment variables rather than mocks. TypeScript strictness is enforced via a repo-wide tsc --noEmit typecheck script, and GitHub Actions workflows (qa.yml) run install, lint, and test jobs on every push and pull request, with a separate scheduled Semgrep scan for security issues — a more rigorous CI setup than most client SDKs carry.

API Design The defining ergonomic choice is that the builder chain’s shape mirrors the REST path exactly, so apiRoot.withProjectKey({projectKey}).carts().withId({ID}).get().execute() reads as a literal transcription of GET /{projectKey}/carts/{ID}, minimizing the gap between reading the platform’s HTTP API docs and writing code against it. Every request and response is fully typed, so consumers get IDE autocomplete for query parameters and response fields across the entire API surface without consulting external documentation. The tradeoff is that onboarding requires understanding the builder-chain pattern itself before it becomes fluent, and error feedback is whatever the underlying HTTP layer returns rather than SDK-specific validation, but for a generated client covering this many endpoints consistently, the discoverability-through-typing tradeoff is a strong one.