Platform implementation guide

commercetools: build a controlled agentic-commerce path

Use current product projections and versioned cart resources as the merchant-controlled source of truth, with explicit Store, price and inventory context and conflict-safe mutations.

Official sources reviewed 2026-08-27. This date records the documentation review, not a test of a specific merchant store.

Capabilities confirmed in official documentation

• Product Projections represent product data as visible to customers and can target current or staged data. The API is read-only; product management uses the Products API.
• A Store projection can filter locales, embedded prices by distribution channels and countries, inventory availability by supply channels, and products or variants by Product Selection.
• Price selection can choose a best-matching embedded or standalone price using currency, country, customer group and channel inputs.
• A cart Line Item is a snapshot of the current Product Projection when a variant is added. Product changes do not update the Line Item automatically; the cart can be recalculated on demand.
• A Store-bound cart checks product selection, store availability, locale, distribution-channel pricing and supply-channel inventory before copying product data into a Line Item.
• Versioned resources require the current version for update and delete requests. A mismatch returns ConcurrentModification, and clients must use the latest returned version for follow-up requests.
• Orders are created from active carts. commercetools also warns that a 500 response can occur even if an action completed, so clients should verify resource state before retrying.

Implementation sequence

1. Use the current, published Product Projection for public discovery. Keep staged data behind an editorial or administrative boundary.
2. Bind every discovery and cart operation to the intended Store, locale, country, currency, customer group, distribution channel and supply channel.
3. Resolve and record the exact variant plus selected price. Do not assume that the prices array, best-matching price field and inventory projection represent the same context without matching inputs.
4. Recalculate the cart before buyer confirmation when product, price, discount, tax or inventory may have changed since the Line Item snapshot was created.
5. Send the latest resource version with every mutation. On ConcurrentModification or an ambiguous server error, retrieve the resource and reconcile state before retrying.

Scenarios to test before claiming support

• A staged product differs from current or a product becomes unpublished, and public discovery must not expose the draft or unavailable item.
• The selected Store filters out the variant, locale, distribution-channel price or supply-channel inventory expected by the client.
• A product or price changes after it was added to the cart and the Line Item remains stale until explicit recalculation.
• Two clients update the cart using the same version and one receives ConcurrentModification without losing the other update.
• A 500 response follows cart or order creation and the client checks the supplied unique identifier or resource state before retrying.
• An anonymous shopper signs in and the configured cart merge behavior produces the expected single active cart without duplicate items.

Evidence to retain from the test

• Record the project key, Store key, Product Projection mode, locale, country, currency, customer group and channel inputs used for each response.
• Capture product and variant IDs, selected price, projected availability, cart ID, Line Item snapshot, resource version and recalculated totals before order creation.
• For conflicts and ambiguous errors, retain the rejected version, error type, subsequent resource read and expected versus obtained cart or order count.

What the documentation does not establish

• The reviewed commercetools documentation does not establish native ACP, UCP, AP2 or MCP support.
• Headless APIs and flexible data models do not prove that a merchant has implemented an agent-facing contract or autonomous checkout.
• A Product Projection is not proof of current cart price or inventory after a Line Item snapshot has been created.
• Payment settlement, fulfillment, returns and refunds require separate implementation evidence beyond creation of an Order from a Cart.

Evidence boundary

commercetools exposes flexible primitives rather than a ready-made agent contract. Store context, latest resource version and observed cart state must remain explicit at every step.

Use the public signal scanner for a limited external check, then run the test cases above in a controlled environment. Review common failure modes before extending credentials or payment access.