Agentic Commerce Protocol for Magento 2

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": "[email protected]",
    "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

Patterns Used:

Service Contracts (Api/)
Dependency Injection (constructor)
Plugin/Interceptor pattern
Repository pattern
Builder pattern (responses)
Strategy pattern (validators)

🤝 Contributing

Fork the repository
Create feature branch (git checkout -b feature/awesome-feature)
Write tests for new functionality
Ensure all tests pass
Commit with clear message (git commit -m 'feat: add awesome feature')
Push and open Pull Request

Quality Standards:

✅ Unit tests required for new code
✅ Integration tests for API changes
✅ PSR-12 coding standards
✅ Type hints and strict_types
✅ PHPStan level 8 compliance

📄 License

MIT License - see LICENSE file

🔗 Resources

💬 Support

Issues & Questions: GitHub Issues

Maintainer: run_as_root GmbH [email protected]

Version: 1.5 (OpenAI Certification Ready)

🎯 OpenAI Certification Status

Current Compliance: 95% (Spec-Compliant, Awaiting Platform Testing)

Completed:

✅ All required response fields per ACP spec
✅ Correct monetary value format (cents)
✅ Proper status enums
✅ Complete header validation
✅ Product feed spec compliance
✅ Security features (idempotency, replay protection)
✅ 39 comprehensive tests (unit + integration)

Status:

✅ Code complete and spec-compliant
✅ Unit and integration tests passing
⏳ Awaiting OpenAI platform access for live testing
⏳ Merchant application submitted, pending approval

NOT YET TESTED WITH:

❌ Actual ChatGPT Instant Checkout interface
❌ Real OpenAI API calls
❌ OpenAI conformance test suite

Timeline:

⏳ Awaiting OpenAI merchant program approval
Platform testing & conformance tests (est. 2-3 weeks)
Bug fixes from platform testing (est. 1-2 weeks)
Final certification submission
Production deployment

Application: https://chatgpt.com/merchants

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.github/workflows		.github/workflows
Api		Api
Console/Command		Console/Command
Controller/Feed		Controller/Feed
Cron		Cron
Exception		Exception
Logger		Logger
Model		Model
Observer		Observer
Plugin		Plugin
Test		Test
etc		etc
src/Setup/Patch/Data		src/Setup/Patch/Data
view/adminhtml/ui_component		view/adminhtml/ui_component
.gitignore		.gitignore
ENHANCEMENT_PLAN.md		ENHANCEMENT_PLAN.md
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
registration.php		registration.php

License

run-as-root/ACP-for-Magento-2

Folders and files

Latest commit

History

Repository files navigation