Menu
Article

Building the First Magento 2 Integration for OpenAI's Agentic Commerce Protocol

David Lambauer

David Lambauer

• 8 min read

The Future of Commerce is Conversational (But We're Not There Yet)

Imagine browsing for a new laptop by chatting with ChatGPT. You describe what you need, the AI suggests products from your favorite retailer, and you complete the purchase—all without leaving the conversation. No redirects, no "add to cart" buttons, no checkout forms. Just a natural dialogue that ends with "Your order is confirmed."

This isn't science fiction. It's the promise of OpenAI's Agentic Commerce Protocol (ACP), a new open standard developed in partnership with Stripe. And we've just built the first Magento 2 integration for it.

But before you get too excited, let me be brutally honest: This isn't production-ready. We've built something that's 95% spec-compliant with comprehensive tests, but we haven't been able to test it with the actual ChatGPT platform yet. We're still waiting for OpenAI's merchant program approval, and there are significant challenges ahead—especially for European merchants.

Let me walk you through what we built, how the protocol works, and why I think it'll be at least 3-6 months before German merchants can realistically use in-chat purchases.

Understanding the Agentic Commerce Protocol

ACP is an open standard that enables AI assistants to discover products and facilitate purchases directly within conversations. Think of it as a REST API specifically designed for AI-native commerce.

The Three Core Components

  1. Product Feed - A JSON endpoint exposing your catalog in a standardized format that AI can understand
  2. Checkout Session API - A stateful REST API managing the entire purchase flow from cart creation to order completion
  3. Delegated Payment - Stripe handles the actual payment processing, while your API manages the order

How It Works in Practice

When a user asks ChatGPT to "find me wireless headphones under $200," here's what happens:

  1. ChatGPT crawls your product feed (either in real-time or from a cached index)
  2. The AI analyzes products and suggests relevant matches
  3. User says "I'll take the Sony ones"
  4. ChatGPT calls your API: POST /acp/checkout_sessions with the SKU
  5. Your API creates a cart and returns pricing, shipping options, etc.
  6. User provides shipping address conversationally
  7. ChatGPT updates the session: POST /acp/checkout_sessions/{id}
  8. User confirms purchase
  9. Stripe processes payment
  10. Your API creates the order and returns confirmation

The entire flow stays within the chat interface. No redirects, no external checkout pages.

Technical Deep Dive: Building the Magento Integration

The Architecture Challenge

The biggest challenge was mapping ACP's opinionated schema to Magento's flexible architecture. ACP has strict requirements:

  • All monetary values must be non-negative integers (cents, not dollars)
  • Specific status enums: not_ready_for_payment, ready_for_payment, completed, cancelled
  • Structured response objects: line_items, total_details, fulfillment_options
  • Required security headers: Idempotency-Key, Request-Id, Timestamp

Meanwhile, Magento has its own patterns: service contracts, repository patterns, dependency injection, and the Quote-to-Order flow.

Core Components We Built

1. Response Builders

We created dedicated builder classes to transform Magento data into ACP-compliant responses:

// Model/Response/LineItemBuilder.php
private function convertToCents(float $amount): int
{
    return (int)round($amount * 100);
}

public function build(Quote $quote): array
{
    $lineItems = [];
    foreach ($quote->getAllVisibleItems() as $item) {
        $lineItems[] = [
            'id' => 'item_' . $item->getId(),
            'product_id' => $item->getProductId(),
            'quantity' => (int)$item->getQty(),
            'amount' => $this->convertToCents($item->getRowTotal()),
            'tax_amount' => $this->convertToCents($item->getTaxAmount()),
        ];
    }
    return $lineItems;
}

That convertToCents() method is critical. The spec explicitly requires integers—failing this would be an instant certification blocker.

2. Security Validators

ACP requires multiple security layers:

  • Idempotency Keys - We cache these in Redis for 24 hours to prevent duplicate requests
  • Timestamp Validation - 5-minute tolerance window to prevent replay attacks
  • HMAC Signatures - Optional but recommended SHA256 validation
  • Bearer Token Auth - Standard API key authentication
// Model/Auth/TimestampValidator.php
public function validate(int $timestamp): void
{
    $now = time();
    $tolerance = $this->config->getTimestampTolerance(); // 300 seconds default
    
    if ($timestamp < ($now - $tolerance)) {
        throw new LocalizedException(__('Timestamp too old - possible replay attack'));
    }
    
    if ($timestamp > ($now + $tolerance)) {
        throw new LocalizedException(__('Timestamp in future - clock skew?'));
    }
}

3. Product Feed Generator

The product feed needs to be AI-friendly with specific fields:

{
  "products": [
    {
      "id": "24-MB01",
      "title": "Joust Duffle Bag",
      "link": "https://example.com/joust-duffle-bag.html",
      "brand": "Joust",
      "images": [
        "https://example.com/media/catalog/product/m/b/mb01-blue-0.jpg",
        "https://example.com/media/catalog/product/m/b/mb01-blue-1.jpg"
      ],
      "inventory_quantity": 42,
      "enable_search": true,
      "enable_checkout": true,
      "price": 3400,
      "currency": "USD"
    }
  ]
}

Notice the price is 3400 (cents), not 34.00. This consistency matters for AI parsing.

We also added support for configurable products with variants, real-time inventory from Magento's StockRegistry, and multiple images from the product gallery.

4. Real Magento Integration

This isn't a toy implementation. We're using actual Magento Quote objects, which means:

  • Real pricing with catalog rules and promotions
  • Actual tax calculations based on address
  • Live inventory checks
  • Real shipping methods and costs
  • Genuine order creation with increment IDs

When a session is completed, we create a real Magento order, send confirmation emails, and return order tracking URLs.

Current Status: Spec-Compliant but Untested

⚠️ Important Disclaimer

This module is NOT production-ready. Here's the honest truth:

  • ✅ We've implemented 95% of the ACP specification
  • ✅ We've written 39 comprehensive tests (31 unit + 8 integration)
  • ✅ All tests pass with our mocked implementations
  • ❌ We have NOT tested this with the actual ChatGPT platform
  • ❌ We have NOT tested this with real OpenAI API calls
  • ❌ We have NOT run OpenAI's conformance test suite

Why Not?

Because we can't. OpenAI's merchant program is invite-only, and we're still waiting for approval. One of our merchant clients applied weeks ago—no response yet.

We built this module based on the public specification, extensive unit testing, and integration tests that simulate the expected behavior. The code is solid, the architecture is sound, and the tests prove the logic works. But until we can plug this into a real ChatGPT conversation and watch money change hands, it's theoretical.

What Could Go Wrong?

Based on experience with new APIs, here's what I expect when we finally get platform access:

  1. Field Validation Edge Cases - The spec might enforce validation rules not explicitly documented
  2. Timestamp Precision - Clock skew issues are common with strict timestamp requirements
  3. Enum Values - Case sensitivity or additional status values we haven't accounted for
  4. Rate Limiting - Undocumented API limits that break our caching strategy
  5. Webhook Delivery - Retry logic, signature validation, timeout handling

I'd estimate 5-10 issues will surface during real platform testing, most minor but a few potentially requiring significant refactoring. That's why we're calling this "pre-production."

The European Reality Check

Even if our module works perfectly with ChatGPT, there's a bigger problem: The protocol isn't ready for the European market.

Payment Provider Lock-In

ACP currently requires Stripe for payment processing. There's no plugin system, no alternative PSPs, no flexibility.

For US merchants, that's fine. Stripe has 80%+ market penetration.

For German merchants? It's a dealbreaker. The German e-commerce landscape is dominated by:

  • Mollie - Popular in Netherlands/Germany
  • Klarna - Essential for "pay later" options
  • PayPal - Still massive in DACH region
  • Sofort - Bank transfer integration
  • Local methods - iDEAL, Giropay, etc.

Many German merchants don't even have Stripe accounts. Those that do often use it as a backup, not their primary PSP.

What needs to happen: OpenAI needs to either:

  1. Allow merchants to handle payments themselves (delegated checkout, not just delegated payment), or
  2. Partner with additional PSPs and add a provider selection mechanism

Regulatory Uncertainty

European consumer protection laws add complexity:

  • GDPR - What data does OpenAI store about purchases? Where are data processing agreements?
  • Distance Selling Regulations - 14-day return right must be clearly communicated. How does that work in a chat?
  • Legal "Order Confirmation" - German law requires explicit consent for purchases. Does a chat message count?
  • Invoice Requirements - German merchants must provide compliant invoices ("Rechnung"). Does Stripe do this?

These aren't show-stoppers, but they're not trivial either. Each requires legal clarity, UI adjustments, and potentially protocol extensions.

Localization Gaps

The product feed spec is English-centric. German merchants will need:

  • Multilingual product titles and descriptions
  • EUR pricing (currently USD-biased in examples)
  • Local shipping carriers (DHL, Hermes, DPD, not just "Standard Shipping")
  • VAT display requirements (German law requires gross prices, not net)

My Timeline Estimate: 3-6 Months Minimum

Here's my realistic timeline for German merchant viability:

  • Now - Q1 2025: OpenAI rolls out merchant program slowly, US-focused
  • Q1 2025: First round of platform testing, bug fixes, spec clarifications
  • Q2 2025: Protocol v1.1 with multi-PSP support (optimistic)
  • Q2 2025: Mollie/PayPal integration discussions begin
  • Q3 2025: EU regulatory guidance published
  • Q3 2025: First German merchants go live (early adopters with Stripe)
  • Q4 2025: Mainstream German merchant adoption (with Mollie support)

That's assuming everything goes smoothly. Regulatory challenges, privacy concerns, or slow PSP partnerships could push this to 2026.

So Why Build This Now?

Fair question. If it's not production-ready and the market isn't ready, why did we invest the time?

1. Early Mover Advantage

When OpenAI does open the floodgates, we'll have the only proven Magento integration. Merchants will need this, and we'll be years ahead of competitors.

2. Influence the Protocol

By building a real implementation, we've discovered pain points and edge cases. We can contribute to the specification and push for features like multi-PSP support.

3. Learning Investment

AI-native commerce is coming whether we're ready or not. Understanding these patterns now—how AI discovers products, how conversational checkout flows work, what security looks like—is valuable regardless of ACP's success.

4. Open Source Contribution

This is MIT licensed and on GitHub. If the protocol evolves in ways we didn't expect, the community can fork and adapt. If it dies, someone will build something similar, and they'll have our code as a reference.

Try It Yourself (With Caveats)

The module is available on GitHub: run-as-root/ACP-for-Magento-2

Installation

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

Configuration

Go to Stores → Configuration → Agentic Commerce Protocol and set up:

  • API key for OpenAI authentication
  • Stripe secret key (test mode works)
  • Enable product feed
  • Configure security settings (idempotency, timestamps, signatures)

API Endpoints

  • GET /acp/feed - Public product feed
  • POST /rest/V1/acp/checkout_sessions - Create session
  • POST /rest/V1/acp/checkout_sessions/{id} - Update session
  • GET /rest/V1/acp/checkout_sessions/{id} - Get session
  • POST /rest/V1/acp/checkout_sessions/{id}/complete - Complete order
  • POST /rest/V1/acp/checkout_sessions/{id}/cancel - Cancel session

Run the Tests

# Unit tests
cd app/code/RunAsRoot/AgenticCommerceProtocol/Test/Unit
../../../../../vendor/bin/phpunit

# Integration tests (requires Magento test environment)
bin/magento dev:tests:run integration RunAsRoot_AgenticCommerceProtocol

The tests are comprehensive and passing. They prove the logic works. But remember: this hasn't been tested with the actual platform.

What's Next?

We're in a holding pattern until OpenAI grants platform access. Once that happens:

  1. Platform Testing - Run real ChatGPT conversations, complete actual purchases
  2. Bug Fixes - Address issues discovered during testing
  3. Conformance Tests - Pass OpenAI's official test suite
  4. Certification - Submit for official approval
  5. Production Release - Mark as stable, remove pre-production warning

For EU market readiness, we're watching for:

  • Multi-PSP support announcements
  • Mollie partnership discussions
  • EU regulatory guidance
  • Localization improvements in the spec

Final Thoughts

Building this module has been equal parts exciting and frustrating. The protocol is elegant, the vision is compelling, but the execution timeline is unclear.

For US merchants with Stripe: You're in a good position. Watch for platform access invites and be ready to test.

For EU merchants: Temper your expectations. This will take time. If you have Stripe and want to be an early adopter, great. If you rely on Mollie or Klarna, you're probably looking at mid-to-late 2025.

For developers: The code is solid, the architecture is clean, and the tests are comprehensive. It's a good reference implementation even if ACP doesn't become the standard.

We're committed to maintaining this module and pushing it to production when the platform is ready. If you want to contribute, have questions, or need enterprise support, reach out: david@run-as-root.sh

Until then, we wait. And hope OpenAI responds to that merchant application soon.