Commerce Integration Layer overview

B2CB2BB2XB2C CORE COMMERCEB2B CORE COMMERCEB2X CORE COMMERCE
Ask about this Page
Copy for AI
View as Markdown

Concepts and terminology of the Commerce Integration Layer.

What is the Commerce Integration Layer

The Commerce Integration Layer provides a commercetools-hosted Experience API that powers your storefronts, mobile apps, and AI agents by combining commercetools commerce APIs with the other vendor solutions in your stack. Built to be frontend-agnostic, a single instance can serve multiple frontends.

You can wire new experiences in days or weeks, not months, and there is no infrastructure for you to maintain.

Core capabilities
  • Build storefront backends: power the entire customer journey with a single GraphQL API pre-loaded with commerce capabilities, so you don't build from scratch.
  • Compose your stack: extend the Experience API with your own code to inject custom logic and integrate any third-party solution.
What's included
  • Experience API: a Project-scoped GraphQL API that merges a core shopper-facing schema with your custom published extensions.
  • Shopper Identity: comprehensive session management with native support for external authentication services via OpenID Connect.
  • Builder CLI: a dedicated command-line tool to quickly build, validate, and deploy your extensions.
  • Merchant Center: operator UI for configuration and system monitoring.
  • Platform Insights: routes technical logs and metrics directly to your APM.
Out of scope
  • Storefront frontend and hosting.
  • Integration that isn't shopper-facing. Scheduled or event-driven work, such as daily data reconciliation between systems, belongs in commercetools Connect.
  • Vendor selection and catalog modeling.
To enable a Project and publish your first extension, see Get started.

Intended audience

The Commerce Integration Layer is for developers building storefronts and apps on the commercetools platform. You write clients that query the Experience API with a shopper session, and you author extensions that add the capabilities your storefront needs.
See Enrollment for more details.

Key concepts

The following sections explain the key concepts and terminology of the Commerce Integration Layer.

Experience API

The Experience API is the Commerce Integration Layer's single GraphQL API per Project. It combines a core subgraph (the shopper-facing schema for catalog, cart, checkout, orders, accounts, and B2B) with any extensions you publish, and serves the result as one schema.
It's designed for shopper-facing use cases and keeps the commercetools trust boundary server-side. For the entry points and how the schema is shaped, see the Experience API overview.

Sessions

Every request to the Experience API carries a session token as a bearer credential. A session represents an anonymous or signed-in shopper together with their presentment context (locale, currency, and country).

Sessions are stateless: the token is a self-contained JWT that seals the Project's commercetools token inside it, so there is no server-side session store and the commercetools token never reaches the browser. You mint and manage sessions through the Shopper Identity's identity endpoints, not through the Experience API. For more details, see Hosts and authorization.

Router

A per-project router fronts the Commerce Integration Layer at the public edge. It serves the Experience API under /{projectKey}/main/graphql and forwards each request to that Project's core subgraph.

The router validates and plans queries against the Project's published schema at the edge. The router treats the Project in the URL as a hint; the Commerce Integration Layer re-checks it against the session token, so routing is never the trust boundary.

Extensions

An extension is a small GraphQL subgraph that you write and publish to add capabilities to your Project's API. The Commerce Integration Layer composes your extension with the core subgraph and serves the merged result, with no redeploy.

Extensions can:

  • Add fields and types to the graph, such as a new root query, an extra field on Product, or a value computed from data the Commerce Integration Layer already owns. See Schema extensions.
  • Call external services, and return the result as part of the graph.
  • Intercept writes using Managed API Extensions, a synchronous callback that validates, modifies, or blocks a cart or order write before commercetools persists it.
Because the Commerce Integration Layer holds your commercetools credentials and runs extension code in a restricted sandbox, your extension code never handles a commercetools token. For steps on how to write and publish extensions, see Getting started and Write schema extensions.

Enrollment

To get access, request enrollment for your Project from your commercetools Account Representative. Once enrolled, the Experience API can be activated for your Project from the Merchant Center.

Until a Project is enrolled and activated, its Experience API and extension endpoints are unavailable.