Agentic commerce

Worked Agentic Commerce samples

An AI shopping agent drives the four operations below in order: fetch the discovery manifest, browse the catalogue, build a cart, and complete checkout under the purchaser’s payment mandate. Substitute your storefront id (org_…) and issued mandate where shown. Successful requests below return raw ACP documents (not the { data, meta } envelope the authenticated Commerce API uses).

1. Catalogue browse

GET /api/v1/public/commerce/acp/{storefrontId}/feed

Return the merchant’s published catalogue. The items array is what the agent presents to the shopper.

cURL

curl "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/.well-known/agentic-commerce" \
  && curl "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/feed"

Node.js

const manifest = await fetch('https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/.well-known/agentic-commerce')
  .then((r) => r.json());

// The manifest names the exact endpoints the agent drives.
const feed = await fetch(manifest.endpoints.productFeed).then((r) => r.json());

console.log(feed.items); // [{ id, title, price, currency, ... }]

Python

import requests

base = "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c"
manifest = requests.get(f"{base}/.well-known/agentic-commerce").json()

# The manifest names the exact endpoints the agent drives.
feed = requests.get(manifest["endpoints"]["productFeed"]).json()

print(feed["items"])

{
  "protocol": "agentic-commerce",
  "protocolVersion": "2025-09-29",
  "count": 2,
  "items": [
    {
      "id": "sku_espresso_1l",
      "title": "Single-origin espresso, 1 L",
      "description": "Washed Ethiopian, roasted weekly.",
      "price": 16.5,
      "currency": "USD",
      "availability": "in_stock",
      "inventoryQuantity": 24,
      "link": "https://acme.example/sku_espresso_1l",
      "category": "coffee"
    },
    {
      "id": "sku_drip_filter_pack",
      "title": "Drip filter pack, 100 ct",
      "description": null,
      "price": 8,
      "currency": "USD",
      "availability": "in_stock",
      "inventoryQuantity": 87,
      "link": null,
      "category": "coffee"
    }
  ],
  "generatedAt": 1793937772450
}

2. Cart build

POST /api/v1/public/commerce/acp/{storefrontId}/checkout

Open a session with the agent’s requested items. Every price on the response is computed server-side against the stored catalogue, so a shopper-facing message tells you when a product was unknown, out of stock, or quantity-clamped.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout" \
  -H "Content-Type: application/json" \
  -d '{"id":"sess_acme_92e4","items":[{"productId":"sku_espresso_1l","quantity":2},{"productId":"sku_drip_filter_pack","quantity":1}]}'

Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      id: 'sess_acme_92e4',
      items: [
        { productId: 'sku_espresso_1l', quantity: 2 },
        { productId: 'sku_drip_filter_pack', quantity: 1 },
      ],
    }),
  },
);
const session = await res.json();
// Persist this snapshot; the update and complete calls round-trip it.

Python

import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout",
    json={
        "id": "sess_acme_92e4",
        "items": [
            {"productId": "sku_espresso_1l", "quantity": 2},
            {"productId": "sku_drip_filter_pack", "quantity": 1},
        ],
    },
)
session = res.json()  # persist this snapshot across update/complete

{
  "id": "sess_acme_92e4",
  "merchantId": "org_8v1a2c",
  "status": "ready_for_payment",
  "currency": "USD",
  "category": null,
  "lineItems": [
    {
      "id": "sku_espresso_1l",
      "productId": "sku_espresso_1l",
      "title": "Single-origin espresso, 1 L",
      "quantity": 2,
      "unitPrice": 16.5,
      "currency": "USD",
      "lineTotal": 33
    },
    {
      "id": "sku_drip_filter_pack",
      "productId": "sku_drip_filter_pack",
      "title": "Drip filter pack, 100 ct",
      "quantity": 1,
      "unitPrice": 8,
      "currency": "USD",
      "lineTotal": 8
    }
  ],
  "itemCount": 3,
  "subtotal": 41,
  "total": 41,
  "messages": [],
  "order": null,
  "createdAt": 1793937842610,
  "updatedAt": 1793937842610
}

Any line’s problem — unknown, out of stock, or clamped quantity — comes back in messages with type: "error" and a code you can surface to the shopper. Repeat a re-priced session through update, or replace items entirely with a POST to checkout/update.

3. Payment-token mint (AP2 mandate issue)

POST /api/v1/commerce/agent-mandate

A mandate is the scoped, spend-capped purchase authorization a principal hands the shopping agent. Issue it on the authenticated Commerce API (API key or session JWT), then hand the returned mandate snapshot to the agent for the pay step below. The completion endpoint only accepts a mandate inside its own scope — the ledger reference in the Commerce API reference describes issue, authorize, charge, verify, and revoke.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \ \
  -H "Content-Type: application/json" \
  -d '{"id":"mandate_acme_shop_1","agentId":"agent_coffee_webshop","principalId":"contact_61f2cdb1","maxPerTransaction":75,"totalCap":250,"currency":"USD","allowedMerchants":["org_8v1a2c"],"allowedCategories":["coffee"],"expiresAt":1793940000000}'

Node.js

import { Orbit } from '@devotel-orbit/node';

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data: mandate } = await orbit.request(
  'POST',
  '/commerce/agent-mandate',
  {
    id: 'mandate_acme_shop_1',
    agentId: 'agent_coffee_webshop',
    principalId: 'contact_61f2cdb1',
    maxPerTransaction: 75,
    totalCap: 250,
    currency: 'USD',
    allowedMerchants: ['org_8v1a2c'],
    allowedCategories: ['coffee'],
    expiresAt: 1793940000000,
  },
);

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
mandate_payload = {
    "id": "mandate_acme_shop_1",
    "agentId": "agent_coffee_webshop",
    "principalId": "contact_61f2cdb1",
    "maxPerTransaction": 75,
    "totalCap": 250,
    "currency": "USD",
    "allowedMerchants": ["org_8v1a2c"],
    "allowedCategories": ["coffee"],
    "expiresAt": 1793940000000,
}
res = requests.post(
    "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate",
    headers=headers,
    json=mandate_payload,
)
mandate = res.json()["data"]

{
  "data": {
    "id": "mandate_acme_shop_1",
    "agentId": "agent_coffee_webshop",
    "principalId": "contact_61f2cdb1",
    "maxPerTransaction": 75,
    "totalCap": 250,
    "currency": "USD",
    "allowedMerchants": ["org_8v1a2c"],
    "allowedCategories": ["coffee"],
    "spent": 0,
    "authorizationCount": 0,
    "status": "active",
    "consentDigest": "9a4c0e1d9b27fcb8a25fede6c1c1ab90512ef0c9...",
    "expiresAt": 1793940000000,
    "createdAt": 1793937855190,
    "updatedAt": 1793937855190,
    "revokedAt": null
  },
  "meta": {
    "request_id": "req_issue_mandate",
    "timestamp": "2026-09-04T14:32:31.590Z"
  }
}

4. Checkout complete

POST /api/v1/public/commerce/acp/{storefrontId}/checkout/complete

The agent’s retirement of the mandate into a settled checkout. The signed request is verified before any priced line is evaluated; the response is a raw ACP receipt. Merchant-side order fulfilment subscribes to the commerce.payment_request.status_changed webhook event.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout/complete" \
  -H "Content-Type: application/json" \
  -H "Signature-Agent: agent_coffee_webshop" \
  -d '{"session":<step 2 session snapshot>,"mandate":<step 3 mandate snapshot>}'

Node.js

const body = {
  session,  // the ready_for_payment snapshot from step 2
  mandate,  // the snapshot returned at step 3
  // The catalogue cannot be supplied here: pricing runs only against
  // the merchant's stored storefront.
};

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout/complete',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      // Web Bot Auth signature header carrying the agent's identity; either a
      // verified Orbit agent key or a merchant-trusted directory entry.
      'Signature-Agent': 'agent_coffee_webshop',
    },
    body: JSON.stringify(body),
  },
);

const receipt = await res.json();
// receipt.session is now "completed"; receipt.order is the settled order.

Python

import requests

payload = {
    "session": session,   # ready_for_payment snapshot from step 2
    "mandate": mandate,   # snapshot returned at step 3
    # The catalogue cannot be supplied here: pricing runs only against
    # the merchant's stored storefront.
}
res = requests.post(
    "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout/complete",
    headers={
        # Web Bot Auth signature header carrying the agent's identity.
        "Signature-Agent": "agent_coffee_webshop",
    },
    json=payload,
)
receipt = res.json()
# receipt["session"] is "completed"; receipt["order"] is the settled order.

{
  "session": {
    "id": "sess_acme_92e4",
    "merchantId": "org_8v1a2c",
    "status": "completed",
    "currency": "USD",
    "category": null,
    "lineItems": [
      {
        "id": "sku_espresso_1l",
        "productId": "sku_espresso_1l",
        "title": "Single-origin espresso, 1 L",
        "quantity": 2,
        "unitPrice": 16.5,
        "currency": "USD",
        "lineTotal": 33
      },
      {
        "id": "sku_drip_filter_pack",
        "productId": "sku_drip_filter_pack",
        "title": "Drip filter pack, 100 ct",
        "quantity": 1,
        "unitPrice": 8,
        "currency": "USD",
        "lineTotal": 8
      }
    ],
    "itemCount": 3,
    "subtotal": 41,
    "total": 41,
    "messages": [],
    "order": {
      "id": "ord_sess_acme_92e4",
      "checkoutSessionId": "sess_acme_92e4",
      "mandateId": "mandate_acme_shop_1",
      "authorizationId": "mandate_acme_shop_1-auth-1",
      "amount": 41,
      "currency": "USD"
    },
    "createdAt": 1793937842610,
    "updatedAt": 1793937855190
  },
  "mandate": {
    "id": "mandate_acme_shop_1",
    "agentId": "agent_coffee_webshop",
    "principalId": "contact_61f2cdb1",
    "maxPerTransaction": 75,
    "totalCap": 250,
    "currency": "USD",
    "allowedMerchants": ["org_8v1a2c"],
    "allowedCategories": ["coffee"],
    "spent": 41,
    "authorizationCount": 1,
    "status": "active",
    "consentDigest": "9a4c0e1d9b27fcb8a25fede6c1c1ab90512ef0c9...",
    "expiresAt": 1793940000000,
    "createdAt": 1793937855190,
    "updatedAt": 1793937855190,
    "revokedAt": null
  },
  "authorization": {
    "authorized": true,
    "reason": "ok",
    "mandateId": "mandate_acme_shop_1",
    "authorizationId": "mandate_acme_shop_1-auth-1",
    "amount": 41,
    "reference": "sess_acme_92e4",
    "remainingCap": 209
  }
}

A 422 at completion carries the deny reason (“exceeds per-transaction cap”, “category not allowed”) so the agent can re-purchase against a corrected cart, not blind-retry the same request.

API Reference

All Endpoints

Worked Agentic Commerce samples

1. Catalogue browse

2. Cart build

3. Payment-token mint (AP2 mandate issue)

4. Checkout complete

​Worked Agentic Commerce samples

​1. Catalogue browse

​2. Cart build

​3. Payment-token mint (AP2 mandate issue)

​4. Checkout complete

Worked Agentic Commerce samples

1. Catalogue browse

2. Cart build

3. Payment-token mint (AP2 mandate issue)

4. Checkout complete