Agentic commerce

{
  "protocol": "agentic-commerce",
  "protocolVersion": "2025-09-29",
  "merchant": {
    "id": "org_8v1a2c",
    "name": "Acme Coffee Roasters",
    "currency": "USD",
    "categories": ["coffee"]
  },
  "capabilities": {
    "discovery": true,
    "checkoutSessions": true,
    "delegatedPayment": true
  },
  "paymentMethods": ["delegated_mandate"],
  "endpoints": {
    "productFeed": "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/feed",
    "checkoutSessionCreate": "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout",
    "checkoutSessionUpdate": "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout/update",
    "checkoutSessionComplete": "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout/complete"
  },
  "generatedAt": 1793937700000
}

{
  "protocol": "agentic-commerce",
  "protocolVersion": "2025-09-29",
  "merchant": {
    "id": "org_8v1a2c",
    "name": "Acme Coffee Roasters",
    "currency": "USD",
    "categories": ["coffee"]
  },
  "capabilities": {
    "discovery": true,
    "checkoutSessions": true,
    "delegatedPayment": true
  },
  "paymentMethods": ["delegated_mandate"],
  "endpoints": {
    "productFeed": "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/feed",
    "checkoutSessionCreate": "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout",
    "checkoutSessionUpdate": "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout/update",
    "checkoutSessionComplete": "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout/complete"
  },
  "generatedAt": 1793937700000
}

ACP transaction round trip: worked sequence

The Agentic Commerce Protocol (ACP) is the storefront surface a third-party AI shopping agent drives end to end: it discovers what you sell, builds a cart, and pays under a mandate the shopper signed. The two discovery reads, the .well-known manifest and the product feed, are unauthenticated and rate-limited per IP, so an agent can fetch them cold with no credential. The three checkout operations are scoped to the storefrontId in the path, and completion additionally verifies the agent’s signature before any charge is evaluated. All five operations return raw ACP documents, not the { data, meta } envelope the authenticated Commerce API uses, and every amount is in major currency units. The four calls below are one continuous transaction against the same storefront (org_8v1a2c) and session (sess_cust_c61f_92e4). Substitute your published storefront id, which you can read from publicUrl on the stored storefront config.

1. Discover the manifest

GET /api/v1/public/commerce/acp/{storefrontId}/.well-known/agentic-commerce

No X-API-Key header is needed: this read is unauthenticated, so an agent that has never seen your storefront before can resolve it. Parse capabilities to check what the storefront supports, and endpoints for the exact paths to call next; the manifest is self-describing, so the agent never has to guess URLs. The same unauthenticated pattern serves the product feed at endpoints.productFeed, whose 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"

Node.js

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

console.log(manifest.capabilities);
// { discovery: true, checkoutSessions: true, delegatedPayment: true }

const feed = await fetch(manifest.endpoints.productFeed).then((r) => r.json());
console.log(feed.items); // [{ id, title, price, currency, availability, ... }]

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()

print(manifest["capabilities"])
feed = requests.get(manifest["endpoints"]["productFeed"]).json()
print(feed["items"])

{
  "protocol": "agentic-commerce",
  "protocolVersion": "2025-09-29",
  "merchant": {
    "id": "org_8v1a2c",
    "name": "Acme Coffee Roasters",
    "currency": "USD",
    "categories": ["coffee"]
  },
  "capabilities": {
    "discovery": true,
    "checkoutSessions": true,
    "delegatedPayment": true
  },
  "paymentMethods": ["delegated_mandate"],
  "endpoints": {
    "productFeed": "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/feed",
    "checkoutSessionCreate": "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout",
    "checkoutSessionUpdate": "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout/update",
    "checkoutSessionComplete": "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout/complete"
  },
  "generatedAt": 1793937700000
}

2. Open a checkout session

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

The session id is opaque and caller-chosen, so put your customer or basket reference in it; it is the handle you correlate the order against later. items comes straight from the feed. Every price in the response is computed server-side against the merchant’s stored catalog, so nothing you send can set a price, and any line that cannot be honoured (unknown product, out of stock, clamped quantity) comes back in messages with a code you can surface to the shopper.

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({
      // Caller-chosen: carry your customer reference in the session id.
      id: 'sess_cust_c61f_92e4',
      merchantId: 'org_8v1a2c',
      items: [
        { productId: 'sku_espresso_1l', quantity: 2 },
        { productId: 'sku_drip_filter_pack', quantity: 1 },
      ],
    }),
  },
);
const session = await res.json();
// Persist this snapshot verbatim: complete round-trips it in step 3.

Python

import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout",
    json={
        "id": "sess_cust_c61f_92e4",
        "merchantId": "org_8v1a2c",
        "items": [
            {"productId": "sku_espresso_1l", "quantity": 2},
            {"productId": "sku_drip_filter_pack", "quantity": 1},
        ],
    },
)
session = res.json()  # persist this snapshot; step 3 round-trips it

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_cust_c61f_92e4",
    "merchantId": "org_8v1a2c",
    "items": [
      { "productId": "sku_espresso_1l", "quantity": 2 },
      { "productId": "sku_drip_filter_pack", "quantity": 1 }
    ]
  }'

{
  "id": "sess_cust_c61f_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
}

A session whose messages contains any type: "error" entry stays not_ready_for_payment and cannot be completed; fix the cart and replace the item set with POST .../checkout/update (replace-items semantics), which re-prices and re-derives the status.

3. Complete checkout under the mandate

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

Completion pays the session under the shopper’s payment mandate: a scoped, spend-capped authorization the merchant issues on the authenticated Commerce API (POST /api/v1/commerce/agent-mandate, described in the Commerce API reference) and hands to the agent. The request body round-trips the two snapshots you already hold, the ready_for_payment session from step 2 and the mandate; the agent identifies itself with the Signature-Agent Web Bot Auth header, and an anonymous or unverifiable caller is rejected before any charge. The session is re-priced server-side once more and the mandate’s caps are re-verified, so the charge cannot exceed what the shopper signed.

Node.js

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 carrying the agent's verified identity.
      'Signature-Agent': 'agent_coffee_webshop',
    },
    body: JSON.stringify({
      session,  // the ready_for_payment snapshot from step 2
      mandate,  // the mandate snapshot issued for this agent
    }),
  },
);
const receipt = await res.json();
// receipt.session.status is "completed"; receipt.session.order is the order.

Python

import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/public/commerce/acp/org_8v1a2c/checkout/complete",
    headers={"Signature-Agent": "agent_coffee_webshop"},
    json={"session": session, "mandate": mandate},
)
receipt = res.json()
print(receipt["session"]["order"]["id"])  # ord_sess_cust_c61f_92e4

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": { "...": "the full ready_for_payment snapshot from step 2" },
    "mandate": { "...": "the mandate snapshot issued for this agent" }
  }'

{
  "session": {
    "id": "sess_cust_c61f_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_cust_c61f_92e4",
      "checkoutSessionId": "sess_cust_c61f_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",
    "spent": 41,
    "authorizationCount": 1,
    "status": "active",
    "totalCap": 250,
    "maxPerTransaction": 75
  },
  "authorization": {
    "authorized": true,
    "reason": "ok",
    "mandateId": "mandate_acme_shop_1",
    "authorizationId": "mandate_acme_shop_1-auth-1",
    "amount": 41,
    "reference": "sess_cust_c61f_92e4",
    "remainingCap": 209
  }
}

The response is the payment capture state: authorization.authorized: true records the mandate charge, authorization.remainingCap shows what the shopper’s cap has left, and session.order is the minted order. On deployments that settle on-chain (x402), authorization additionally carries a settlement receipt with the network and transaction hash; where settlement is not enabled the field is absent and the mandate authorization alone is the capture record.

4. Confirm the order and its state

The ACP edge is stateless by design: the session snapshot round-trips in each request, so the completion receipt from step 3 is the order status. session.order.id is the order to fulfil against, session.order.amount and currency are the captured total, and session.status is the payment state. There is no separate order-status read on the public edge; the merchant’s backend drives fulfilment from this receipt and from the commerce payment events it already receives on its webhooks. The session’s status moves through these states, and the two terminal ones are immutable:

`status`	Payment state
`not_ready_for_payment`	A line problem (see `messages`) blocks payment; re-price with `checkout/update`.
`ready_for_payment`	Priced and payable; waiting on the mandate-gated completion.
`completed`	Mandate authorized and the order minted. Terminal: the session can no longer be updated or completed again.
`canceled`	Terminal: the session can never be completed.

Resending a completed session to checkout/complete or checkout/update is rejected rather than re-charged, so a retried completion is safe: treat the order on the first receipt as authoritative.

Errors worth branching on

Failures on this page keep the platform { error, meta } envelope. Three statuses carry the transactional meaning:

404

{
  "error": {
    "code": "STOREFRONT_NOT_FOUND",
    "message": "No published storefront exists for this merchant",
    "status": 404
  },
  "meta": {
    "request_id": "req_acp404a",
    "timestamp": "2026-10-16T09:12:44Z"
  }
}

A 404 means the storefront id is unknown or the merchant has unpublished it. It fires on every operation on this page, including the manifest, so an agent should treat it as “this merchant is not on ACP” and stop, not retry.

402

{
  "error": {
    "code": "SETTLEMENT_FAILED",
    "message": "On-chain settlement supports USD-priced checkouts only, not EUR",
    "status": 402
  },
  "meta": {
    "request_id": "req_acp402b",
    "timestamp": "2026-10-16T09:13:02Z"
  }
}

A 402 is payment required: on deployments with on-chain settlement enabled, the settlement was rejected or unavailable (a missing or invalid X-PAYMENT header, an unverifiable payment, or a checkout priced in a currency the settlement rail does not accept). The mandate is untouched and the session stays ready_for_payment, so correcting the payment and resending completes the same session.

409

{
  "error": {
    "code": "CONFLICT",
    "message": "This checkout session was already completed by a concurrent request",
    "status": 409
  },
  "meta": {
    "request_id": "req_acp409c",
    "timestamp": "2026-10-16T09:13:19Z"
  }
}

A 409 means another caller modified the same session first, typically a concurrent completion that already minted the order. Do not open a second session: read the order from the winning receipt and continue fulfilment from there. A 422 at completion carries the mandate deny reason (for example, a charge past the per-transaction cap or outside the allowed categories) in error.message, and a 422 at checkout lists the offending lines in messages; branch on those and resend a corrected cart rather than blind-retrying the same body. For the platform-wide decision table these branches plug into, see the error handling guide. For the prose walkthrough of the same round trip, including the merchant-side storefront setup and mandate issue, see Complete a purchase with the Agentic Commerce Protocol.

API Reference

All Endpoints

ACP transaction round trip: worked sequence

1. Discover the manifest

2. Open a checkout session

3. Complete checkout under the mandate

4. Confirm the order and its state

Errors worth branching on

​ACP transaction round trip: worked sequence

​1. Discover the manifest

​2. Open a checkout session

​3. Complete checkout under the mandate

​4. Confirm the order and its state

​Errors worth branching on

ACP transaction round trip: worked sequence

1. Discover the manifest

2. Open a checkout session

3. Complete checkout under the mandate

4. Confirm the order and its state

Errors worth branching on