Agentic Commerce Protocol for Magento 2

October 10, 2025 · View on GitHub

95% OpenAI ACP Spec Compliant | Pre-Production | Awaiting Platform Access

Enable ChatGPT purchases directly from your Magento 2 store using the Agentic Commerce Protocol (ACP) - an open standard by OpenAI and Stripe.

⚠️ Status: This module is spec-compliant and fully tested with unit/integration tests, but has NOT been tested with actual OpenAI ChatGPT platform access. We are awaiting approval from OpenAI's merchant program. Use at your own risk until platform testing is complete.

🚀 Features

✅ OpenAI ACP Specification Compliance (95%)

Checkout Session API:

Enhanced response schema with line_items, total_details, fulfillment_options
All monetary values as integers (cents) per spec
Correct status enums: not_ready_for_payment, ready_for_payment, completed, cancelled
Order tracking with order_url and confirmation_email_sent
Shipping method selection via fulfillment_option_id

Product Feed:

Spec-compliant fields: id, title, link, brand, images, inventory_quantity
Configurable product variants with individual pricing
Multiple image support (full gallery)
Real-time inventory levels
Per-product control flags (acp_enable_search, acp_enable_checkout)
CLI feed generation (bin/magento acp:feed:generate)
Automated feed regeneration (cron every 6 hours)
Static file support for large catalogs (10k+ products)

Security Headers:

Idempotency-Key validation (Redis-backed, 24hr cache)
Request-Id tracking for correlation
Timestamp validation (5min tolerance, prevents replay attacks)
Signature HMAC SHA256 validation (optional, configurable)
API-Version compatibility checking

Core Functionality

✅ Full REST API (5 endpoints: create, get, update, complete, cancel)
✅ Real Magento Quote integration (pricing, taxes, discounts, inventory)
✅ Stripe Delegated Payment with official SDK
✅ Webhook notifications (order.created, order.updated)
✅ Multi-currency support
✅ Database persistence with proper ResourceModel pattern
✅ Automated session cleanup cron job

Security & Enterprise Features

✅ Bearer token API authentication
✅ Idempotency key duplicate prevention
✅ Timestamp-based replay attack prevention
✅ HMAC signature validation (configurable)
✅ Encrypted secret storage
✅ ACL permissions
✅ Comprehensive audit logging

Developer Experience

✅ 39 Tests (31 unit + 8 integration) covering critical paths
✅ Monetary conversion accuracy tests
✅ Security validation tests
✅ End-to-end API flow tests
✅ PSR-12 compliant code
✅ Proper Magento service contracts
✅ Full dependency injection
✅ Type-safe (strict_types everywhere)

📋 Requirements

Magento: 2.4.6+
PHP: 8.1+
Composer: 2.x
Redis: For caching (idempotency keys)
Stripe Account: For payment processing

📦 Installation

Via Composer (Recommended)

composer require run-as-root/module-agentic-commerce-protocol
bin/magento module:enable RunAsRoot_AgenticCommerceProtocol
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Manual Installation

git clone https://github.com/run-as-root/ACP-for-Magento-2.git
mkdir -p app/code/RunAsRoot/AgenticCommerceProtocol
cp -r ACP-for-Magento-2/* app/code/RunAsRoot/AgenticCommerceProtocol/
bin/magento module:enable RunAsRoot_AgenticCommerceProtocol
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

⚙️ Configuration

Navigate to Stores > Configuration > Agentic Commerce Protocol

1. General Settings

Enable Module: Turn on/off the ACP functionality
API Key: Generate secure key for OpenAI authentication
Test Mode: Enable verbose logging for development
Session Retention: Days to keep completed sessions (default: 30)

2. Security Settings (NEW)

Enable Signature Validation: HMAC SHA256 request signing
Signature Secret: Shared secret for signature verification
Timestamp Tolerance: Replay attack window (default: 300 seconds)

3. Product Feed

Enable Product Feed: Allow ChatGPT product discovery
Include Categories: Filter by category (empty = all)
Maximum Products: Limit feed size (default: 1000)

4. Webhook Settings

Enable Webhooks: Send order events to OpenAI
Endpoint URL: OpenAI webhook receiver
Signing Secret: HMAC signature for webhooks

5. Stripe Payment

Enable Stripe: Use Stripe for payment processing
Secret Key: Your Stripe API key (sk_live_* or sk_test_*)
Test Mode: Use Stripe test environment

🔌 API Endpoints

Checkout Session API (Requires Authentication)

All endpoints require these headers:

Authorization: Bearer <api-key>
Idempotency-Key: <unique-request-id>
Request-Id: <correlation-id>
Timestamp: <unix-timestamp>

Create Session

POST /rest/V1/acp/checkout_sessions
Content-Type: application/json

{
  "items": [
    {"sku": "24-MB01", "quantity": 2}
  ]
}

Update Session

POST /rest/V1/acp/checkout_sessions/{id}

{
  "buyer": {
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "fulfillment_address": {
    "first_name": "John",
    "last_name": "Doe",
    "address_line1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US"
  },
  "fulfillment_option_id": "flatrate_flatrate"
}

Get Session

GET /rest/V1/acp/checkout_sessions/{id}

Complete Session

POST /rest/V1/acp/checkout_sessions/{id}/complete

{
  "payment_data": {
    "token": "pm_stripe_token_here"
  }
}

Cancel Session

POST /rest/V1/acp/checkout_sessions/{id}/cancel

Product Feed (Public)

GET /acp/feed

Returns JSON feed with all visible products in ACP format.

🔧 CLI Commands

Generate Static Product Feed

bin/magento acp:feed:generate

# Options:
bin/magento acp:feed:generate --store=1 --output=custom_feed.json

Generates a static JSON feed file in var/acp/feed.json for improved performance with large catalogs.

Benefits:

Pre-generate feeds for 10k+ product catalogs
Reduce real-time server load
Automated regeneration via cron (every 6 hours)
Custom output paths for multi-store setups

🧪 Testing

Run Unit Tests (31 tests)

cd Test/Unit
../../../vendor/bin/phpunit

Run Integration Tests (8 tests)

cd magento
bin/magento dev:tests:run integration RunAsRoot_AgenticCommerceProtocol

Test Coverage:

✅ Monetary conversion accuracy
✅ Security header validation
✅ Response schema compliance
✅ End-to-end checkout flows
✅ Idempotency and replay protection

🏗️ Architecture

Follows Magento 2 best practices:

Structure:

Model/
├── Response/              # ACP response builders
│   ├── CheckoutSessionResponseBuilder.php
│   ├── LineItemBuilder.php
│   ├── TotalDetailsBuilder.php
│   └── FulfillmentOptionsBuilder.php
├── Auth/                  # Security validators
│   ├── HeaderValidator.php
│   ├── IdempotencyManager.php
│   ├── SignatureValidator.php
│   └── TimestampValidator.php
├── CheckoutSessionManagement.php
├── Order/OrderManagement.php
└── Feed/ProductFeedGenerator.php

Plugin/
├── ApiAuthenticationPlugin.php
└── CheckoutSessionResponsePlugin.php

Test/
├── Unit/                  # 31 unit tests
└── Integration/          # 8 integration tests