Skip to content

AgenticCheckout

Jump to bottom
KristofersOzolinsMagebit edited this page Oct 14, 2025 · 1 revision

Agentic Checkout (ACP compatible)

Implemented features checklist

  • Create/Retrieve/Update/Complete/Cancel checkout sessions
  • Custom router with configurable base path (default checkout_sessions)
  • Idempotency, API version and request ID headers in responses
  • Delegated payment storage endpoint
  • Webhook dispatch for order events (created/updated)
  • Configurable links (ToS/Privacy/etc.) attached to session responses

On this page

Overview

This guide explains how the Agentic Checkout API is implemented in Magento 2 using the Magebit Agentic Commerce module, aligned with the ACP spec. It covers endpoints, request/response objects, routing, idempotency, and extension points for payments and validation.

Endpoints and routes

Base frontName: agentic_commerce with a configurable router base path.

  • Router base path: configurable, default checkout_sessions
  • Effective paths (examples shown with default):
    • Create checkout session: POST /checkout_sessions → agentic_commerce/checkout_sessions/index
    • Retrieve session: GET /checkout_sessions/{session_id} → agentic_commerce/checkout_sessions/retrieve
    • Update session: POST /checkout_sessions/{session_id} → agentic_commerce/checkout_sessions/update
    • Complete session: POST /checkout_sessions/{session_id}/complete → agentic_commerce/checkout_sessions/complete
    • Cancel session: POST /checkout_sessions/{session_id}/cancel → agentic_commerce/checkout_sessions/cancel
    • Delegated payment store: POST /agentic_commerce/delegate_payment/index

Notes:

  • The router parses the base path and infers action by method or suffix.
  • The module sets session_id automatically from the URL segment when applicable.

Request/response schema overview

  • Requests are validated and transformed into typed objects:
    • Create: CreateCheckoutSessionRequestInterface
    • Update: UpdateCheckoutSessionRequestInterface
    • Complete: CompleteCheckoutSessionRequestInterface
    • Delegated Payment: DelegatePaymentRequestInterface
  • Responses:
    • CheckoutSessionResponseInterface (includes line items, totals, fulfillment options, payment provider, buyer, currency, links, messages, status)

Checkout session flow

  1. Create session
  • Call create to obtain session_id (masked guest cart id).
  • Provide items, buyer, fulfillment address as available; totals and options are computed.
  1. Update session (optional, repeatable)
  • Send changes (items, address, fulfillment option id) to recalc totals and options.
  1. Retrieve session (optional)
  • Get current state for UI/agent display (messages, status, totals, options).
  1. Complete session
  • Provide payment_data.token (vault/payment method token) and optional billing address and buyer.
  • Module places order, maps order to session, sets success message, and dispatches webhook.
  1. Cancel session (optional)
  • Deactivates cart if not already placed.

Delegated payments

See the detailed guide: DelegatedPayments.md

Idempotency and compliance

  • Incoming requests validated with ComplianceService (API token, allowed headers, etc.).
  • Idempotency is handled using key and cached response storage; headers are echoed in responses:
    • Idempotency-Key, API-Version, Request-Id
  • Errors are normalized via ErrorResponseInterface.

Configuration

Admin: Stores -> Settings -> Configuration -> Magebit -> Agentic Commerce

  • Agentic Checkout
    • Router Base Path (default checkout_sessions)
    • API Token (optional)
    • Order Success Page (redirect target for agentic_commerce/checkout/order)
    • Checkout Session Links (array)
    • Enable Webhooks (on/off)
    • Order status mapping to ACP lifecycle

Extension points

  • Validation: CartValidatorInterface and composite
  • Payment vaulting: PaymentMethodVaultHandlerInterface and PaymentHandlerPool
  • Session response building: converters like CartItemToLineItem, CartToFulfillmentOptions, CartToTotals, CartToPaymentProvider, CartToBuyer
  • Webhooks: WebhookService and data mappers (e.g., OrderToOrderCreatedUpdatedWebhook)
  • Routing: base path via config, custom controller actions if needed

References

  • ACP Checkout concepts: https://developers.openai.com/commerce/guides/key-concepts

Clone this wiki locally