agentic-commerce-protocol

# Agentic Commerce Protocol (ACP) Skill > Skill by [ara.so](https://ara.so) — AI Agent Skills collection. ## Overview The Agentic Commerce Protocol (ACP) is an open standard for connecting buyers, their AI agents, and businesses to complete purchases seamlessly. Maintained by OpenAI and Stripe, ACP enables AI agents to initiate and complete commerce transactions on behalf of users. **Key Capabilities:** - AI agents can discover and purchase products/services - Businesses expose checkout endpoints to AI agents - Payment providers handle secure payment token exchange - Support for carts, orders, fulfillment, and extensions - Date-based versioning (`YYYY-MM-DD` format) **Current Version:** `2026-04-17` ## Installation & Setup ### For Merchants (Implementing Checkout Endpoints) 1. **Clone the specification repository:** ```bash git clone https://github.com/agentic-commerce-protocol/agentic-commerce-protocol.git cd agentic-commerce-protocol ``` 2. **Review the OpenAPI specification:** ```bash # Latest stable spec cat spec/2026-04-17/openapi/openapi.agentic_checkout.yaml ``` 3. **Install dependencies for your implementation:** Node.js/Express example: ```bash npm init -y npm install express body-parser express-validator ``` Python/Flask example: ```bash pip install flask flask-cors jsonschema ``` ### For AI Agent Developers Review the specification and integrate with a reference implementation: - **OpenAI:** https://developers.openai.com/commerce/ - **Stripe:** https://docs.stripe.com/agentic-commerce ## Core Concepts ### 1. Agentic Checkout Flow The basic checkout flow involves these endpoints: - `POST /agentic-checkout/capabilities` - Discover seller capabilities - `POST /agentic-checkout/create-checkout` - Initialize checkout session - `POST /agentic-checkout/update-checkout` - Update checkout details - `POST /agentic-checkout/confirm-checkout` - Finalize and confirm purchase ### 2. Payment Handlers ACP supports multiple payment handler types: - **Delegate Payment Handler** - Agent handles payment collection - **Seller-Backed Payment Handler** - Seller collects payment directly - **Payment Link Handler** - Redirect to payment page ## Implementation Examples ### Basic Express.js Seller Implementation ```javascript const express = require('express'); const bodyParser = require('body-parser'); const { v4: uuidv4 } = require('uuid'); const app = express(); app.use(bodyParser.json()); // In-memory store (use database in production) const checkoutSessions = new Map(); // Capabilities endpoint app.post('/agentic-checkout/capabilities', (req, res) => { res.json({ version: '2026-04-17', supported_features: [ 'cart', 'orders', 'fulfillment', 'extensions' ], payment_handlers: [ { type: 'delegate_payment', supported_methods: ['card', 'bank_transfer'] } ], extensions: [ { type: 'discount', supported_discount_types: ['percentage', 'fixed_amount'] } ] }); }); // Create checkout endpoint app.post('/agentic-checkout/create-checkout', (req, res) => { const { items, buyer_info, payment_handler } = req.body; // Validate required fields if (!items || !Array.isArray(items) || items.length === 0) { return res.status(400).json({ error: { type: 'invalid_request', message: 'Items are required' } }); } // Create session const sessionId = uuidv4(); const session = { id: sessionId, status: 'open', items: items.map(item => ({ id: item.id, name: item.name, quantity: item.quantity || 1, unit_price: item.unit_price, total: (item.quantity || 1) * item.unit_price })), buyer_info: buyer_info || {}, payment_handler, created_at: new Date().toISOString() }; // Calculate totals session.subtotal = session.items.reduce((sum, item) => sum + item.total, 0); session.total = session.subtotal; checkoutSessions.set(sessionId, session); res.json({ checkout_id: sessionId, status: 'open', items: session.items, subtotal: session.subtotal, total: session.total, payment_handler: session.payment_handler }); }); // Update checkout endpoint app.post('/agentic-checkout/update-checkout', (req, res) => { const { checkout_id, items, buyer_info, shipping_address } = req.body; const session = checkoutSessions.get(checkout_id); if (!session) { return res.status(404).json({ error: { type: 'checkout_not_found', message: 'Checkout session not found' } }); } if (session.status !== 'open') { return res.status(400).json({ error: { type: 'invalid_state', message: 'Checkout is not in open state' } }); } // Update session if (items) { session.items = items.map(item => ({ id: item.id, name: item.name, quantity: item.quantity || 1, unit_price: item.unit_price, total: (item.quantity || 1) * item.unit_price })); session.subtotal = session.items.reduce((sum, item) => sum + item.total, 0); session.total = session.subtotal; } if (buyer_info) { session.buyer_info = { ...session.buyer_info, ...buyer_info }; } if (shipping_address) { session.shipping_address = shipping_address; } res.json({ checkout_id: session.id, status: session.status, items: session.items, subtotal: session.subtotal, total: session.total }); }); // Confirm checkout endpoint app.post('/agentic-checkout/confirm-checkout', (req, res) => { const { checkout_id, payment_token } = req.body; const session = checkoutSessions.get(checkout_id); if (!session) { return res.status(404).json({ error: { type: 'checkout_not_found', message: 'Checkout session not found' } }); } if (session.status !== 'open') { return res.status(400).json({ error: { type: 'invalid_state', message: 'Checkout is not in open state' } }); } // Process payment (integrate with payment processor) // For demo purposes, we'll simulate success session.status = 'completed'; session.payment_token = payment_token; session.completed_at = new Date().toISOString(); const orderId = `ord_${uuidv4()}`; session.order_id = orderId; res.json({ checkout_id: session.id, status: 'completed', order_id: orderId, confirmation: { order_number: orderId, total: session.total, items: session.items } }); }); app.listen(3000, () => { console.log('ACP server listening on port 3000'); }); ``` ### Python/Flask Seller Implementation ```python from flask import Flask, request, jsonify from flask_cors import CORS import uuid from datetime import datetime app = Flask(__name__) CORS(app) # In-memory store checkout_sessions = {} @app.route('/agentic-checkout/capabilities', methods=['POST']) def capabilities(): return jsonify({ 'version': '2026-04-17', 'supported_features': [ 'cart', 'orders', 'fulfillment' ], 'payment_handlers': [ { 'type': 'delegate_payment', 'supported_methods': ['card'] } ] }) @app.route('/agentic-checkout/create-checkout', methods=['POST']) def create_checkout(): data = request.json items = data.get('items', []) if not items: return jsonify({ 'error': { 'type': 'invalid_request', 'message': 'Items are required' } }), 400 session_id = str(uuid.uuid4()) # Process items processed_items = [] subtotal = 0 for item in items: quantity = item.get('quantity', 1) unit_price = item.get('unit_price', 0) total = quantity * unit_price processed_items.append({ 'id': item.get('id'), 'name': item.get('name'), 'quantity': quantity, 'unit_price': unit_price, 'total': total }) subtotal += total session = { 'id': session_id, 'status': 'open', 'items': processed_items, 'buyer_info': data.get('buyer_info', {}), 'payment_handler': data.get('payment_handler'), 'subtotal': subtotal, 'total': subtotal, 'created_at': datetime.utcnow().isoformat() } checkout_sessions[session_id] = session return jsonify({ 'checkout_id': session_id, 'status': 'open', 'items': processed_items, 'subtotal': subtotal, 'total': subtotal }) @app.route('/agentic-checkout/confirm-checkout', methods=['POST']) def confirm_checkout(): data = request.json checkout_id = data.get('checkout_id') payment_token = data.get('payment_token') session = checkout_sessions.get(checkout_id) if not session: return jsonify({ 'error': { 'type': 'checkout_not_found', 'message': 'Checkout session not found' } }), 404 if session['status'] != 'open': return jsonify({ 'error': { 'type': 'invalid_state', 'message': 'Checkout is not in open state' } }), 400 # Process payment session['status'] = 'completed' session['payment_token'] = payment_token order_id = f"ord_{uuid.uuid4()}" session['order_id'] = order_id return jsonify({ 'checkout_id': checkout_id, 'status': 'completed', 'order_id': order_id, 'confirmation': { 'order_number': order_id, 'total': session['total'], 'items': session['items'] } }) if __name__ == '__main__': app.run(port=3000, debug=True) ``` ### Capability Negotiation ```javascript // Client-side capability check async function checkSellerCapabilities(sellerUrl) { const response = await fetch(`${sellerUrl}/agentic-checkout/capabilities`, { method: 'POST', headers: { 'Content-Type': 'application/json', } }); const capabilities = await response.json(); // Check if seller supports required features const requiredFeatures = ['cart', 'orders']; const hasRequiredFeatures = requiredFeatures.every(feature => capabilities.supported_features?.includes(feature) ); return { compatible: hasRequiredFeatures, capabilities }; } ``` ### Extension Support (Discounts) ```javascript // Apply discount extension app.post('/agentic-checkout/update-checkout', (req, res) => { const { checkout_id, extensions } = req.body; const session = checkoutSessions.get(checkout_id);