MaxMage_AgenticCommerce (Magento 2 x ChatGPT Agentic Checkout) — WIP

⚠️ Project status: Experimental / In Development (pre-release). APIs and behavior may change without notice.

MaxMage_AgenticCommerce is a Magento 2 module that implements the Agentic Checkout flow so orders can be created, updated, and completed directly from ChatGPT using the Agentic Commerce Protocol (ACP).

• Spec (Agentic Checkout): https://developers.openai.com/commerce/specs/checkout
• Overview (ACP): https://developers.openai.com/commerce

This module keeps URLs exactly like the spec (no /rest/V1) using a Magento custom router and JSON controllers. It validates required headers, verifies HMAC signatures, enforces idempotency, and returns spec-shaped session payloads.

Features

• Exact endpoints (frontend area):
  • POST /checkout_sessions – Create session
  • GET /checkout_sessions/{id} – Read session
  • POST /checkout_sessions/{id} – Update session (patch semantics)
  • POST /checkout_sessions/{id}/complete – Complete (place order)
  • POST /checkout_sessions/{id}/cancel – Cancel session
• Spec headers enforced:
  • Authorization, Idempotency-Key, Request-Id, Content-Type, Signature, Timestamp, API-Version
• Signature verification: Base64(HMAC-SHA256(raw_body, shared_secret))
• Idempotency: DB-backed replay for safe retries
• Response headers echoed: Idempotency-Key, Request-Id
• Spec-shaped responses: line_items, fulfillment_options, totals, messages, links, status, and order on completion
• CSRF-safe API controllers via CsrfAwareActionInterface
• Status: alpha / work-in-progress

Requirements

• PHP 8.1+
• Magento 2.4.6+
• MySQL 8+

Installation (from source)

# Place module in app/code
mkdir -p app/code/MaxMage/AgenticCommerce
# copy repo files into that directory

bin/magento module:enable MaxMage_AgenticCommerce
bin/magento setup:upgrade

Composer (when published):

composer require maxmage/module-agentic-commerce:0.1.0-dev
bin/magento module:enable MaxMage_AgenticCommerce
bin/magento setup:upgrade

Configuration

Admin: Stores -> Configuration -> MaxMage -> Agentic Commerce

• Shared Secret — used to verify Signature HMAC
• API Version — must match API-Version header (e.g. 2025-09-12)
• Timestamp Skew (seconds) — allowed drift for Timestamp

Usage (cURL)

Create

BODY='{"items":[{"product_id":"sku-123","quantity":2}],"currency":"USD","customer":{"email":"[email protected]"},"shipping_address":{"line1":"123 Main St","city":"Springfield","country":"US","postal_code":"12345"}}'
TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "YOUR_SHARED_SECRET" -binary | openssl base64)

curl -i -X POST https://your.domain/checkout_sessions   -H "Authorization: Bearer YOUR_TOKEN"   -H "Idempotency-Key: idem-$(uuidgen)"   -H "Request-Id: req-$(uuidgen)"   -H "Content-Type: application/json"   -H "Signature: $SIG"   -H "Timestamp: $TS"   -H "API-Version: 2025-09-12"   --data-binary "$BODY"

Complete

BODY='{"payment_data":{"token":"tok_example","provider":"your_psp"}}'
TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "YOUR_SHARED_SECRET" -binary | openssl base64)

curl -i -X POST https://your.domain/checkout_sessions/<session_id>/complete   -H "Authorization: Bearer YOUR_TOKEN"   -H "Idempotency-Key: idem-$(uuidgen)"   -H "Request-Id: req-$(uuidgen)"   -H "Content-Type: application/json"   -H "Signature: $SIG"   -H "Timestamp: $TS"   -H "API-Version: 2025-09-12"   --data-binary "$BODY"

Development Notes

• Endpoints live in the frontend area with a custom Router that forwards:
  • /checkout_sessions -> agentic/Session/Create
  • /checkout_sessions/{id} -> agentic/Session/Get or Update
  • /checkout_sessions/{id}/complete -> agentic/Session/Complete
  • /checkout_sessions/{id}/cancel -> agentic/Session/Cancel
• Controllers extend a base class that:
  • bypasses CSRF (API style)
  • validates required headers
  • verifies signatures and timestamps
  • enforces idempotency (DB table mm_agentic_idempotency)
  • echoes response headers

DB Tables

• mm_agentic_idempotency — idempotency replay storage
• mm_agentic_session — maps session_id <-> quote_id, tracks status

Roadmap

• Webhooks: order.created, order.updated
• OpenAPI for module (basic spec provided in openapi.yaml)
• MSI/stock checks & richer messages[]
• i18n for totals/messages (via Accept-Language)
• Tests & CI

License

• PolyForm Noncommercial 1.0.0 — noncommercial use permitted.
• Commercial use requires a paid license — see COMMERCIAL-LICENSE.md.