Intermediate · 15 min

Agentic Commerce (ACP)

Build AI-powered shopping experiences with the Agentic Commerce Protocol. Enable autonomous agents to browse products, create checkout sessions, and complete purchases.

Prerequisites

Podium SDK installed and configured
Basic understanding of AI agents or automation
Stripe account for payment processing

The Agentic Commerce Protocol (ACP) provides a streamlined API for AI agents to interact with your commerce platform. It exposes a product feed optimized for agent consumption and a simplified checkout flow.

Fetch the product feed

Get a paginated list of products formatted for agent consumption:

agent.ts

// Get product feed for agents
const feed = await client.agentic.list({
  page: 1,
  limit: 20,
  categories: '1,2,3', // Optional: filter by categories
})

console.log(feed)
// {
//   products: [
//     { id: '...', title: '...', price: 29.99, available: true, imageUrl: '...' },
//     ...
//   ],
//   pagination: { page: 1, limit: 20, total: 150 }
// }

Create a checkout session

Initialize a checkout session with selected products. The session tracks cart state and payment intent:

agent.ts

// Create checkout session
const session = await client.agentic.create({
  requestBody: {
    items: [
      { id: 'product_xyz', quantity: 1 },
      { id: 'product_abc', quantity: 2 },
    ],
    email: 'customer@example.com', // Optional
  },
})

console.log(session)
// {
//   id: 'session_...',
//   items: [...],
//   subtotal: 89.97,
//   clientSecret: 'pi_..._secret_...', // For Stripe payment
// }

Update shipping address

Add or update shipping details. This triggers shipping rate calculation:

agent.ts

// Update checkout session with shipping
const updated = await client.agentic.update({
  id: session.id,
  requestBody: {
    email: 'customer@example.com',
    shippingAddress: {
      name: 'John Doe',
      line1: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      postalCode: '94102',
      country: 'US',
    },
  },
})

console.log(updated.shippingFee) // Calculated shipping cost

Complete the payment

Use the clientSecret with Stripe to complete payment on the frontend:

checkout.tsx

// Frontend: Confirm payment with Stripe
import { loadStripe } from '@stripe/stripe-js'

const stripe = await loadStripe('pk_...')
const { error } = await stripe.confirmPayment({
  clientSecret: session.clientSecret,
  confirmParams: {
    return_url: 'https://yourapp.com/order-complete',
  },
})

if (error) {
  console.error('Payment failed:', error.message)
}

Complete Example

Here's a complete working example combining all the steps:

complete-example.ts

import { createPodiumClient } from '@podiumcommerce/node-sdk'

const client = createPodiumClient({
  apiKey: process.env.PODIUM_API_KEY,
})

async function agentPurchase(productIds: string[], customerEmail: string) {
  // 1. Create checkout session
  const session = await client.agentic.create({
    requestBody: {
      items: productIds.map(id => ({ id, quantity: 1 })),
      email: customerEmail,
    },
  })

  // 2. Add shipping address
  await client.agentic.update({
    id: session.id,
    requestBody: {
      shippingAddress: {
        name: 'Agent Customer',
        line1: '123 AI Boulevard',
        city: 'San Francisco',
        state: 'CA',
        postalCode: '94102',
        country: 'US',
      },
    },
  })

  // 3. Return session for payment completion
  return {
    sessionId: session.id,
    clientSecret: session.clientSecret,
    total: session.subtotal + (session.shippingFee || 0),
  }
}

NFT Rewards Token Presales

Explore the full API

See all available endpoints and parameters in the API reference.

API Docs