Experience API overview

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

Endpoints, sessions, and the operations of the Experience API.

The Commerce Integration Layer serves one GraphQL API per Project, the Experience API. The router combines the Core Subgraph with the extensions you publish and serves them as one schema.
The Experience API is separate from the HTTP API and has its own hosts and authorization. Each request carries a shopper session token instead of a commercetools access token.

Endpoints

Experience API endpoint

The router serves the Experience API at /{projectKey}/main/graphql. Send GraphQL requests with POST and an Authorization: Bearer <session token> header. For the host, see Hosts and authorization.

The router validates each query against the published schema of your Project. This schema includes Project-specific types and fields, such as product types with their typed attributes and Custom Fields.

Introspection isn't available on the public GraphQL endpoint. To explore the schema and run operations, use commercetools integration-layer explore in the CLI. To download the SDL, use commercetools integration-layer schema fetch.

Identity endpoints

You create and manage sessions with REST identity endpoints. GraphQL operations never create, renew, or rotate a session.

Sessions and authorization

Every GraphQL request requires a session token. A session represents an anonymous or signed-in shopper and holds the presentment context: locale, currency, and country. Price-dependent and locale-dependent fields read this context.

A session is a stateless JWT that contains a sealed commercetools access token:

  • The browser only holds the session token. The commercetools access token stays on the server.
  • The Commerce Integration Layer validates the sealed token on every request, so revoking a session takes effect immediately.
If a query needs presentment and the session has none, the request fails with a SESSION_MISSING_PRESENTMENT error. The Commerce Integration Layer doesn't apply a default.
To create a session with presentment, see Get started.

Schema entry points

The Core Subgraph groups its operations by area. Each area has a reference page with the arguments, return types, and example requests of its operations. Your Project's schema also contains fields derived from its configuration and from published extensions.

AreaQueriesMutations
Common typesviewer, node
Catalogproduct, products, search, categories, category
Cartcart, shippingMethodsForCart, paymentMethodsaddCartLine, addCartLines, updateCartLineQuantity, updateCartLineCustomFields, removeCartLine, clearCart, applyDiscountCode, removeDiscountCode, setShippingAddress, setBillingAddress, setCustomerEmail, setPurchaseOrderNumber, selectShippingMethod, clearShippingMethod, beginPayment
Orderorders, ordercheckout, guestCheckout, placeOrder, reorder, requestReturn, cancelOrder
Accountmeregister, updateProfile, setMiddleName, setTitle, setSalutation, setDateOfBirth, setCompanyName, setVatId, changePassword, changeEmail, addAddress, updateAddress, removeAddress, setDefaultAddress
Shopping ListshoppingLists, shoppingListcreateShoppingList, updateShoppingList, addShoppingListLine, addToShoppingList, changeShoppingListLineQuantity, removeShoppingListLine, deleteShoppingList
B2B: Business Units and AssociatesbusinessUnits, businessUnit, activeBusinessUnitcreateBusinessUnit, changeBusinessUnitName, setBusinessUnitContactEmail, addBusinessUnitAddress, updateBusinessUnitAddress, removeBusinessUnitAddress, addAssociate, updateAssociateRoles, removeAssociate
B2B: QuotesquoteRequests, quoteRequest, quotes, quoterequestQuote, cancelQuoteRequest, acceptQuote, declineQuote, renegotiateQuote
B2B: Approvalsapprovals, approval, approvalRules, approvalRuleapproveOrder, rejectOrder, createApprovalRule, updateApprovalRule, setApprovalRuleActive

To place an Order, use the mutation that matches the checkout:

  • beginPayment: starts a Checkout flow for a Customer or a guest. Checkout creates the Order.
  • checkout: places the Order for a signed-in Customer.
  • guestCheckout: places the Order for a guest.
  • placeOrder: places a B2B Order as the Associate in the selected Business Unit. The permissions of the Associate and the Approval Rules of the Business Unit apply.
checkout, guestCheckout, and placeOrder place the Order without collecting a payment. To collect a payment with these mutations, use an extension.
You change the session context, such as presentment, the selected Business Unit, or the Store, with the identity endpoints, not with GraphQL mutations. For example, register creates a Customer, and you then sign that Customer in with a session grant on the identity endpoint.

Extensibility model

The Core Subgraph exposes its top-level resources as federation entities. An extension can add fields to these entities without redeclaring the whole type. For the list of extensible types, see the entity catalog.

Extensions can also:

  • Compute fields from data that the Commerce Integration Layer owns, with @requires.
  • Return entity stubs that the router resolves to full objects.
  • Register Managed API Extensions that run on write operations.
For the SDL and resolver details, see Write Schema Extensions.