Developer’s Guide: Exposing ACP‑Compliant Endpoints on a Legacy Tech Stack

The Problem: You Want Agentic Commerce, But You Have a Monolith

Your marketing team is buzzing about Agentic Commerce. They want your products discoverable in ChatGPT. They want instant AI checkout.

But your reality is a 10‑year‑old monolithic backend, a SOAP API no one wants to touch, and a database schema that predates modern e‑commerce standards.

The good news? You don’t need to rewrite your legacy stack to support the Agentic Commerce Protocol (ACP). ACP is designed as a lightweight interaction layer, not a platform replacement. You can build an "ACP Adapter" pattern that sits in front of your legacy system, translating modern JSON‑based agent requests into whatever archaic logic your backend understands.

This guide is for engineers. We’ll look at the specific endpoints you need to build, how to map them to legacy data, and how to handle state without breaking your old order management system (OMS).

1. The Architecture: The "Sidecar" Adapter

Do not try to bake ACP endpoints directly into your legacy controller logic. That path leads to madness.

Instead, build a standalone ACP Adapter Service (Node.js, Go, or Python are great for this). This service acts as a translation layer:

1. Ingress: Accepts standard RESTful ACP requests (Search, Cart, Checkout).
2. Translation: Converts these into your legacy system’s native tongue (direct SQL queries, internal API calls, or SOAP requests).
3. Egress: Returns the standardized ACP JSON response to the agent.

This keeps your monolith untouched and lets you iterate on the agentic experience quickly.

2. The Must-Have Endpoints

To be minimally compliant with ACP, your adapter needs to expose just three core interaction patterns.

A. Discovery (GET /products)

Agents need to search your catalog. Your legacy system likely has a massive product table with 50 columns. The agent only needs the semantic essentials.

The Adapter Logic:

• Input: Accepts semantic filters (e.g., query="running shoes", min_price=50).
• Legacy Mapping: Maps these to your existing SOLR, Elasticsearch, or SQL LIKEqueries.
• Transformation: Maps your messy internal column names (p_desc_long_v2) to clean ACP schema fields (description).
• Output: Returns a simplified JSON list of products.

Pro Tip: If your legacy search is slow, cache a lightweight "Agent Feed" in Redis that your adapter reads from, refreshing it every hour.

B. Cart Management (POST /cart)

Agents build carts programmatically. They don't have sessions or cookies in the traditional browser sense.

The Adapter Logic:

• Stateless to Stateful: ACP requests might be stateless. Your legacy system probably requires a session ID. Your adapter should generate a temporary "Guest Session" in your legacy backend for each agent interaction.
• Input: product_id, quantity, options.
• Legacy Action: Calls your internal AddToCart function.
• Output: Returns a standardized Cart object with calculated totals (tax, shipping estimation).

C. Checkout & Payment (POST /checkout)

This is the critical step. ACP uses delegated payment tokens (e.g., from Stripe), whereas your legacy system expects a credit card number.

The Adapter Logic:

• Token Handling: The agent sends a payment_token. Do not try to decrypt this.
• Processor Mapping: Pass this token to your payment processor's modern API (most legacy gateways now support tokenized auth).
• Order Injection: Once payment succeeds, inject the order into your OMS using a "System User" or "Agent User" account so your fulfillment team sees it as a normal order.
• Tagging: Crucial—tag these orders as source: agentic in your database so you don't mess up your marketing attribution.

3. Handling "Legacy" Quirks

Inventory Latency

Legacy systems often batch-update inventory. Agents expect real-time answers.

• Solution: Implement a "Safety Stock" buffer in your adapter. If your legacy DB says 5 left, tell the agent 3 left. This prevents overselling due to sync lag.

Complex Options (The "Matrix" Problem)

Your legacy DB handles variants (Size: M, Color: Blue) as separate SKUs, or maybe as a confusing blob string.

• Solution: Normalize this in the adapter. Expose clean variant_ids to the agent. Do not force the AI to understand your internal SKU logic (SHIRT-BLU-M-V2).

Shipping Calculations

Your shipping logic is buried in a stored procedure from 2012.

• Solution: Don't rewrite it. Have the adapter call that stored procedure with the cart payload to get the rate, then format the result for the agent.

4. Security & Authentication

ACP endpoints must be public-facing but secured.

1. mTLS or API Keys: Use standard API Gateway authentication to ensure only authorized agents (or aggregators) can hit your adapter.
2. Rate Limiting: AI agents can be chatty. Implement strict rate limiting (e.g., Redis-based token bucket) on your adapter to protect your fragile legacy DB from being hammered.

5. Deployment Strategy

Don't do a "Big Bang" release.

1. Read-Only Mode: Deploy the adapter with only the Search (GET /products) endpoint first. Test if agents can discover your catalog.
2. Pilot Mode: Enable Checkout for internal test users or a whitelist of low-risk SKUs.
3. Full Rollout: Open the gates once you confirm that agentic orders are flowing correctly into your fulfillment queue.

Summary: The "Strangler Fig" Approach

By building an ACP Adapter, you are applying the Strangler Fig pattern. You build new, modern functionality (Agentic Commerce) around the edges of your old system.

• You don't rewrite the monolith.
• You don't break existing web checkouts.
• You do unlock a massive new revenue channel with just a thin translation layer.

This is the pragmatic way to let your 10-year-old stack talk to the future.