# Commerce Integration Layer overview

**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.

```mermaid
%%{init: {"flowchart": {"rankSpacing": 28, "nodeSpacing": 24, "padding": 6, "diagramPadding": 4}}}%%
flowchart BT
	Clients["<div style='width:640px; padding:8px 0;'><span style='font-size:21px; font-weight:700;'>Shopper's clients</span><br/><span style='font-size:17px; color:rgb(75,85,99);'>Web storefront, mobile app or agent · Only holds a session token</span></div>"]

	subgraph CIL [" "]
		subgraph ExpAPI [" "]
			ExpTitle["<div style='width:640px; text-align:center; padding:6px 0 10px 0;'><span style='font-size:20px; font-weight:700; color:rgb(17,24,39);'>Experience API</span><br/><span style='font-size:17px; color:rgb(75,85,99);'>One merged GraphQL API to power all your customer-facing experiences</span></div>"]
			
			CoreSubgraph["<div style='width:300px; padding:8px 0;'><span style='font-size:20px; font-weight:700;'>Core subgraph</span><br/><span style='font-size:17px; color:rgb(75,85,99);'>Default commerce flows</span></div>"]
			Extensions["<div style='width:300px; padding:8px 0;'><span style='font-size:20px; font-weight:700;'>Extensions</span><br/><span style='font-size:17px; color:rgb(75,85,99);'>You write, commercetools runs</span></div>"]
		end

		%% Invisible wrapper, defined after ExpAPI, so the CIL <--> Clients arrow anchors on CILTitle and stops at the CIL border
		subgraph CILTop [" "]
			CILTitle["<div style='width:640px; text-align:center; padding:4px 0 10px 0;'><span style='font-size:26px; font-weight:800; color:rgb(90,69,254);'>Commerce Integration Layer</span><br/><span style='font-size:17px; color:rgb(107,114,128);'>Operated by commercetools</span></div>"]
			ShopperIdentity["<div style='width:640px; padding:8px 0;'><span style='font-size:21px; font-weight:700;'>Shopper Identity</span><br/><span style='font-size:17px; color:rgb(75,85,99);'>Mints sessions · Supports external authentication services</span></div>"]
		end
	end

	Platform["<div style='width:300px; padding:8px 0;'><span style='font-size:21px; font-weight:700;'>commercetools platform</span><br/><span style='font-size:17px; color:rgb(75,85,99);'>Catalog, Carts, Orders, B2B, etc</span></div>"]
	External["<div style='width:300px; padding:8px 0;'><span style='font-size:21px; font-weight:700;'>External services</span><br/><span style='font-size:17px; color:rgb(75,85,99);'>Any public API: Search, Taxes, etc</span></div>"]

	%% Visible Connections
	CIL <--> Clients
	Platform <--> CoreSubgraph
	External <-.-> Extensions

	%% Invisible Layout Ranks
	ShopperIdentity ~~~ CILTitle
	ExpTitle ~~~ ShopperIdentity
	CoreSubgraph ~~~ ExpTitle
	Extensions ~~~ ExpTitle

	%% Node & Subgraph Styling
	classDef default font-family:sans-serif;
	classDef clientNode fill:#ffffff,stroke:#8A92A6,stroke-width:2px,rx:12px,ry:12px;
	classDef titleNode fill:transparent,stroke:transparent,stroke-width:0px;
	classDef identityNode fill:#ffffff,stroke:#9D8CF2,stroke-width:1.5px,rx:8px,ry:8px;
	classDef coreNode fill:#ffffff,stroke:#9D8CF2,stroke-width:1.5px,rx:6px,ry:6px;
	classDef extNode fill:#ffffff,stroke:#9D8CF2,stroke-width:1.5px,stroke-dasharray: 4 4,rx:6px,ry:6px;
	classDef platformNode fill:#F6F4FF,stroke:#5A45FE,stroke-width:2px,rx:10px,ry:10px;
	classDef extServicesNode fill:#ffffff,stroke:#8A92A6,stroke-width:2px,stroke-dasharray: 5 5,rx:10px,ry:10px;

	class Clients clientNode;
	class CILTitle titleNode;
	class ShopperIdentity identityNode;
	class ExpTitle titleNode;
	class CoreSubgraph coreNode;
	class Extensions extNode;
	class Platform platformNode;
	class External extServicesNode;

	style CIL fill:#F7F8FF,stroke:#6250E8,stroke-width:2px,rx:16px,ry:16px;
	style CILTop fill:transparent,stroke:transparent;
	style ExpAPI fill:#ffffff,stroke:#9D8CF2,stroke-width:1.5px,rx:8px,ry:8px;

	linkStyle 0 stroke:#64748B,stroke-width:2px;
	linkStyle 1 stroke:#5A45FE,stroke-width:2px;
	linkStyle 2 stroke:#8A92A6,stroke-width:2px,stroke-dasharray: 4 4;
```

**What's included**

- **Experience API**: a Project-scoped [GraphQL API](/commerce-integration-layer/experience-api-overview.md) that merges a core shopper-facing schema with your custom published [extensions](/commerce-integration-layer/overview.md#extensions).
- **Shopper Identity**: comprehensive [session management](/commerce-integration-layer/hosts-and-authorization.md) with native support for [external authentication services](/commerce-integration-layer/hosts-and-authorization.md#idpsessionrequest) via OpenID Connect.
- **Builder CLI**: a dedicated [command-line tool](/commerce-integration-layer/development/get-started.md) 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](/connect/overview).
- Vendor selection and catalog modeling.

To enable a Project and publish your first extension, see [Get started](/commerce-integration-layer/development/get-started.md).

## 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](/commerce-integration-layer/overview.md#sessions), and you author [extensions](/commerce-integration-layer/overview.md#extensions) that add the capabilities your storefront needs.

See [Enrollment](/commerce-integration-layer/overview.md#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](/commerce-integration-layer/overview.md#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](/commerce-integration-layer/experience-api-overview.md).

### 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](/commerce-integration-layer/hosts-and-authorization.md#identity-endpoints), not through the Experience API. For more details, see [Hosts and authorization](/commerce-integration-layer/hosts-and-authorization.md).

### 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](/commerce-integration-layer/schema-extensions.md).
- Call external services, and return the result as part of the graph.
- Intercept writes using [Managed API Extensions](/commerce-integration-layer/managed-api-extensions.md), 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](/commerce-integration-layer/development/get-started.md) and [Write schema extensions](/commerce-integration-layer/development/writing-schema-extensions.md).

## 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.

## Related pages

- [Area overview page with navigation](/commerce-integration-layer.md)
- [Next page: GraphQL federation](/commerce-integration-layer/graphql-federation.md)
- [Search documentation and API specs](/search.md)