Commerce API

Commerce lets a customer start shopping on one channel and finish on another — one cart, one checkout state machine, reconciled against whichever channel actually captures the payment. It also covers the “let an AI agent buy on the customer’s behalf” surfaces: scoped payment mandates, machine-to-machine metered sessions, and the storefront protocols third-party shopping agents (ChatGPT Instant Checkout, Google AP2-style agents) speak. Every handler re-derives totals and prices server-side, so a client-forged subtotal can never pass reconciliation. Every snapshot (cart, mandate, session, subscription) is a serializable object your application round-trips in the request body — this API computes the next valid state, your application is responsible for persisting it. (The conversational commerce checkout guide walks the cart → checkout flow end to end; the worked samples below extend to the agent-mandate, MPP, DCB, ACP/UCP, and subscriptions clusters.) Base path: /api/v1/commerce Authentication: API key (X-API-Key) or session JWT. Every response carries the same envelope: a data payload and a meta block with the request_id you quote when tracing a call with support.

Using the SDKs

Prefer the typed client. The Node SDK ships orbit.commerce.* helpers for the core cart surface — create, merge, transition, reconcile-payment, checkout-channel, abandonment-check — and the generic request() keeps auth/retries and the { data, meta } envelope identical for the rest of this page:

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

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

const { data: cart } = await orbit.commerce.createCart("cart_abc123");

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("POST", "/commerce/cart", {"cartId": "cart_abc123"})

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Raw curl in the body of this page works identically. Full SDK index at SDK quickstart.

Cart & checkout

One cart snapshot that any channel — WhatsApp Pay, RCS catalog carousels, Apple Messages for Business, Instagram DM product shares — folds contributions into.

Method	Path	Purpose
`POST`	`/cart`	Create a fresh, empty cart in the `browsing` state
`POST`	`/cart/merge`	Fold a per-channel order contribution into the cart, re-deriving totals
`POST`	`/cart/transition`	Apply a checkout event (illegal transitions reject with `VALIDATION_ERROR`)
`POST`	`/cart/reconcile-payment`	Match a payment captured on any channel against the cart subtotal
`POST`	`/cart/checkout-channel`	Resolve an ordered checkout-channel preference, restricted to capable channels
`POST`	`/cart/abandonment-check`	True when the cart has gone idle past a threshold while still recoverable

Step 1 — open the cart:

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/cart \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "cartId": "cart_abc123" }'

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

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

const { data: cart } = await orbit.commerce.createCart("cart_abc123");

The cart snapshot you persist and round-trip in later calls:

{
  "data": {
    "cartId": "cart_abc123",
    "state": "browsing",
    "lines": [],
    "totals": { "subtotal": 0, "currency": "USD" }
  },
  "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-08-26T00:00:00.000Z" }
}

Step 2 — drive the checkout state machine. Send the snapshot you persisted plus one event; the response is the next valid state:

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/cart/transition \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cart": { "cartId": "cart_abc123", "...": "the snapshot returned by /cart" },
    "event": "ADD_ITEM"
  }'

An out-of-order event is refused without touching the snapshot you sent — the 422 envelope names the event that failed:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "cannot apply event \"REQUEST_PAYMENT\" while the cart is browsing"
  },
  "meta": { "request_id": "req_b2c3d4e5", "timestamp": "2026-08-26T00:00:00.000Z" }
}

Round-trip the whole snapshot back even when the response added fields you did not send — extra keys are ignored on the way in.

Hosted pay-by-link

A channel-agnostic hosted checkout URL — the fallback when checkout-channel returns no native option (SMS, email, Telegram, Viber, or a voice-IVR readout + QR code).

Method	Path	Purpose
`POST`	`/payment-request`	Mint a fresh hosted PSP-checkout link
`POST`	`/payment-request/render`	Render the link’s content for one specific channel
`POST`	`/payment-request/transition`	Advance the link’s lifecycle
`POST`	`/payment-request/reconcile`	Match a captured PSP payment against the request

Mint the link — one snapshot, reused for every channel that ends up delivering it:

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/payment-request \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "hostedBaseUrl": "https://pay.example.com/checkout",
    "amount": 49.99,
    "currency": "USD",
    "description": "October reorder",
    "successUrl": "https://store.example.com/paid"
  }'

{
  "data": {
    "requestId": "pay_abc123",
    "hostedUrl": "https://pay.example.com/checkout/pay_abc123",
    "amount": 49.99,
    "currency": "USD",
    "state": "created"
  },
  "meta": { "request_id": "req_c3d4e5f6", "timestamp": "2026-08-26T00:00:00.000Z" }
}

Render the link for the channel you deliver on — the voice channel shapes a spoken readout, a messaging channel the short body text. A render never mutates the request snapshot; it only shapes how the URL arrives:

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/payment-request/render \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "request": { "requestId": "pay_abc123", "...": "the snapshot returned by /payment-request" },
    "channel": "sms"
  }'

A channel that is not in the tenant’s capability set is refused with the same 422 envelope — the request snapshot is left untouched, so you can retry with a different channel:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "channel \"voice\" is not a capable checkout channel for this tenant"
  },
  "meta": { "request_id": "req_d4e5f6g7", "timestamp": "2026-08-26T00:00:00.000Z" }
}

In-thread channel checkout

Native checkout without the buyer leaving the conversation — WhatsApp Pay where Meta supports it (India UPI, Brazil Pix, Singapore), the hosted link everywhere else; same pattern for RCS.

Method	Path	Purpose
`POST`	`/whatsapp-checkout`	Resolve an in-thread WhatsApp checkout
`POST`	`/rcs-checkout`	Resolve an in-thread RCS checkout

Resolve an in-thread checkout for the cart — the response is a PaymentRequest snapshot that either binds a native channel button or falls back to the hosted link:

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/whatsapp-checkout \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cart": { "cartId": "cart_abc123", "...": "the snapshot returned by /cart" },
    "hostedBaseUrl": "https://pay.example.com/checkout"
  }'

{
  "data": {
    "checkoutId": "cart_abc123-wa-1",
    "channel": "whatsapp",
    "native": false,
    "hostedUrl": "https://pay.example.com/checkout/cart_abc123-wa-1",
    "state": "created"
  },
  "meta": { "request_id": "req_e5f6g7h8", "timestamp": "2026-08-26T00:00:00.000Z" }
}

native: false means Meta does not support in-thread pay for the buyer’s country — deliver the hosted URL and close out with /payment-request/reconcile; /rcs-checkout returns the same shape.

Agent payment mandates

The authorization layer that lets a voice or chat agent complete a purchase under a scoped, revocable, spend-capped consent the customer (the “principal”) issued once — modeled on the AP2 agent-payments pattern. A mandate carries a per-transaction cap, a total spend cap, an optional merchant/category allowlist, and a tamper-evident consent digest re-verified before every spend.

Method	Path	Purpose
`POST`	`/agent-mandate`	Issue a fresh mandate
`POST`	`/agent-mandate/authorize`	Dry-run a charge against a mandate without advancing spend
`POST`	`/agent-mandate/charge`	Authorize and commit a charge (rejects out-of-scope charges)
`POST`	`/agent-mandate/revoke`	Withdraw consent — terminal
`POST`	`/agent-mandate/verify`	Recompute the consent digest; reports tamper-evidence for auditors
`POST`	`/agent-mandate/network-token`	Mint a card-network agent token (Mastercard Agent Pay) in place of a hosted link, where the pilot is provisioned

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": "mnd_abc123", "agentId": "agt_shopping", "principalId": "cnt_abc123",
    "maxPerTransaction": 50, "totalCap": 200, "currency": "USD",
    "allowedMerchants": ["store.example.com"],
    "allowedCategories": ["electronics"]
  }'

Dry-run a charge against the mandate — the decision is returned without advancing spend:

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/authorize \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mandate": { "id": "mnd_abc123", "...": "the snapshot returned by /agent-mandate" },
    "charge": {
      "amount": 29.99, "currency": "USD",
      "merchant": "store.example.com", "category": "electronics",
      "reference": "order_9f8e7d"
    }
  }'

200 on the allow case — in-scope merchant + category, under both caps:

{
  "data": {
    "authorization": {
      "authorized": true,
      "reason": "ok",
      "authorizationId": "mnd_abc123-auth-1",
      "amount": 29.99,
      "currency": "USD",
      "merchant": "store.example.com",
      "reference": "order_9f8e7d",
      "remainingCap": 170.01
    }
  },
  "meta": { "request_id": "req_5e6f7a8b", "timestamp": "2026-08-26T00:00:00.000Z" }
}

The deny case also returns 200 (spend never advances); the reason names the scope check that failed — a merchant off the allowlist reports merchant_not_allowed:

{
  "data": {
    "authorization": {
      "authorized": false,
      "reason": "merchant_not_allowed",
      "authorizationId": "mnd_abc123-auth-1",
      "amount": 29.99,
      "currency": "USD",
      "merchant": "other-shop.example.com",
      "reference": "order_9f8e7e",
      "remainingCap": 200
    }
  },
  "meta": { "request_id": "req_9c0d1e2f", "timestamp": "2026-08-26T00:00:00.000Z" }
}

Other deny reasons a caller can branch on: revoked, expired, exhausted, integrity_failed (consent-digest tamper, also reported by /agent-mandate/verify), invalid_amount, currency_mismatch, category_not_allowed, exceeds_per_transaction, exceeds_total_cap. /agent-mandate/charge commits the same checks and surfaces the deny as a 422 VALIDATION_ERROR; /agent-mandate/network-token is a card-network pilot surface and is not live on most deployments — expect 503 NETWORK_TOKEN_NOT_CONFIGURED there.

Metered agent-to-agent sessions (MPP)

A pre-authorized, spend-capped, time-bounded session for machine-to-machine consumption of your own APIs or agent services — open a session once, then meter successive micropayments against it.

Method	Path	Purpose
`POST`	`/mpp-session`	Open a pre-authorized session
`POST`	`/mpp-session/call`	First-contact meter + settle: 402 payment challenge, then commit with `X-PAYMENT`
`POST`	`/mpp-session/meter`	Dry-run meter a call without settling
`POST`	`/mpp-session/revoke`	Revoke a session
`POST`	`/mpp-session/verify`	Verify a session’s integrity

/mpp-session/call is dark unless settlement is enabled for the deployment — an ungated call returns 503 MPP_SETTLEMENT_NOT_ENABLED. When it is on, settlement rides the x402 payment challenge: step 1 requests without a payment header and gets a 402 challenge; step 2 retries with the X-PAYMENT header and commits. Step 1 — no X-PAYMENT header → 402 challenge (spend untouched):

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/mpp-session/call \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "session": { "id": "mpp_abc123", "...": "the snapshot returned by /mpp-session" },
    "call": { "amount": 0.02, "resource": "search.rank-product", "reference": "tool_0192" }
  }'

{
  "error": "X-PAYMENT header required",
  "paymentRequirements": {
    "amount": "20000",
    "resource": "search.rank-product",
    "sessionId": "mpp_abc123"
  }
}

Step 2 — retry with the signed payment header → 200, spend commits only once settlement succeeds:

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/mpp-session/call \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <signed x402 payment payload>" \
  -d '{
    "session": { "id": "mpp_abc123", "...": "the snapshot returned by /mpp-session" },
    "call": { "amount": 0.02, "resource": "search.rank-product", "reference": "tool_0192" }
  }'

{
  "data": {
    "session": { "id": "mpp_abc123", "status": "active", "spent": 0.02, "callCount": 1 },
    "meter": {
      "authorized": true,
      "reason": "ok",
      "meterId": "mpp_abc123-call-1",
      "amount": 0.02,
      "resource": "search.rank-product",
      "reference": "tool_0192",
      "remainingCap": 9.98
    },
    "settlement": { "success": true, "transaction": "0xabc123", "network": "base" }
  },
  "meta": { "request_id": "req_a4b5c6d7", "timestamp": "2026-08-26T00:00:00.000Z" }
}

A call over the cap returns 200 with authorized: false (reason exceeds_per_call_cap or exceeds_session_cap) and settlement: null — the dry-run /mpp-session/meter exposes the same decision shape without asking for payment at all.

Direct carrier billing (DCB)

Charge to the customer’s mobile carrier bill instead of a card — merchant onboarding, the charge lifecycle, and settlement reconciliation on top of the carrier-billing network API.

Method	Path	Purpose
`POST`	`/dcb/merchant`	Onboard / reconfigure a DCB merchant (settlement currency, category, per-transaction cap, operator coverage)
`POST`	`/dcb/charge`	Validate + initiate a charge against the merchant’s coverage and cap
`POST`	`/dcb/operator-request`	Build the operator-billing request body for an initiated charge
`POST`	`/dcb/charge/capture`	Capture an initiated charge
`POST`	`/dcb/charge/fail`	Mark an initiated charge failed (terminal)
`POST`	`/dcb/charge/refund`	Refund a captured charge
`POST`	`/dcb/charge/chargeback`	Record a chargeback
`POST`	`/dcb/reconcile`	Reconcile a settlement batch

Initiate a charge — the merchant snapshot you configured at /dcb/merchant, plus the buyer’s number. Operator coverage is tenant-owned: onboard only the country/operator pairs your deployment actually supports (entries marked pilot are not live coverage).

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/dcb/charge \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant": { "merchantId": "mch_abc123", "...": "the snapshot returned by /dcb/merchant" },
    "charge": {
      "id": "dcb_9f8e7d",
      "phoneNumber": "+15551234567",
      "country": "US",
      "operator": "ExampleMobile",
      "amount": 4.99,
      "currency": "USD",
      "description": "Game credits pack"
    }
  }'

{
  "data": {
    "id": "dcb_9f8e7d",
    "merchantId": "mch_abc123",
    "country": "US",
    "operator": "ExampleMobile",
    "buyerMsisdnMasked": "+1•••••4567",
    "amount": 4.99,
    "currency": "USD",
    "description": "Game credits pack",
    "status": "initiated",
    "capturedAmount": 0,
    "refundedAmount": 0
  },
  "meta": { "request_id": "req_c8d9e0f1", "timestamp": "2026-08-26T00:00:00.000Z" }
}

Capture it once the operator dip (shaped at /dcb/operator-request) comes back confirmed:

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/dcb/charge/capture \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "charge": { "id": "dcb_9f8e7d", "...": "the snapshot returned by /dcb/charge" } }'

{
  "data": {
    "id": "dcb_9f8e7d",
    "status": "captured",
    "capturedAmount": 4.99,
    "refundedAmount": 0
  },
  "meta": { "request_id": "req_d2e3f4a5", "timestamp": "2026-08-26T00:00:00.000Z" }
}

Refund a captured charge — posting back the captured snapshot with a reason is all the route needs:

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/dcb/charge/refund \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "charge": { "id": "dcb_9f8e7d", "...": "the captured charge snapshot" }, "reason": "buyer_request" }'

AI-shopping-agent storefronts (ACP / UCP)

The external protocol surface a third-party AI shopping agent (e.g. ChatGPT Instant Checkout) drives against your storefront: discover your catalog, open a cart/checkout session, then pay under a signed agent-payment mandate. Pricing is always re-derived server-side against your catalog, so an agent can never check out at a price you didn’t publish.

Method	Path	Purpose
`POST`	`/agentic/manifest`	Build the Agentic Commerce Protocol (ACP) discovery manifest
`POST`	`/agentic/feed`	Normalize your catalog into the ACP product feed
`POST`	`/agentic/checkout`	Open an ACP checkout session, priced server-side
`POST`	`/agentic/checkout/update`	Re-price a session for a changed item set
`POST`	`/agentic/checkout/complete`	Complete checkout under a signed payment mandate
`POST`	`/ucp/manifest`	Build the Universal Commerce Protocol (UCP) storefront manifest
`POST`	`/ucp/catalog`	Build the UCP product catalog
`POST`	`/ucp/cart`	Open a UCP cart session
`POST`	`/ucp/cart/update`	Re-price a UCP cart session
`POST`	`/ucp/cart/complete`	Complete a UCP cart under a signed mandate

Build the ACP discovery manifest — the JSON a shopping agent fetches to learn your catalog endpoints and accepted payment methods. baseUrl must be an HTTPS origin your endpoint paths join onto; categories are optional.

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/agentic/manifest \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "storefront_abc123",
    "merchantName": "Example Storefront",
    "baseUrl": "https://commerce.example.com/agentic",
    "currency": "USD",
    "categories": ["electronics", "accessories"]
  }'

{
  "data": {
    "protocol": "agentic-commerce",
    "protocolVersion": "2025-09-29",
    "merchant": {
      "id": "storefront_abc123",
      "name": "Example Storefront",
      "currency": "USD",
      "categories": ["electronics", "accessories"]
    },
    "capabilities": {
      "discovery": true,
      "checkoutSessions": true,
      "delegatedPayment": true
    },
    "paymentMethods": ["delegated_mandate"],
    "endpoints": {
      "productFeed": "https://commerce.example.com/agentic/feed",
      "checkoutSessionCreate": "https://commerce.example.com/agentic/checkout",
      "checkoutSessionUpdate": "https://commerce.example.com/agentic/checkout/update",
      "checkoutSessionComplete": "https://commerce.example.com/agentic/checkout/complete"
    },
    "generatedAt": 1787520000000
  },
  "meta": { "request_id": "req_1f2a3b4c", "timestamp": "2026-08-26T00:00:00.000Z" }
}

Running baseUrl values on .example.com are demonstrations only — publish your own origin. The UCP manifest endpoints (/ucp/manifest, /ucp/catalog) follow the same request/response shape.

Subscriptions

Recurring “subscribe & save” orders on top of one-time checkout — a schedule tracks the interval and next-charge date; each renewal reuses the same agent-payment-mandate authorization the customer already consented to, so there’s no re-prompt per cycle.

Method	Path	Purpose
`POST`	`/subscriptions`	Start a subscription off an existing cart, authorized against a mandate
`POST`	`/subscriptions/list`	Annotate + sort subscriptions by next-charge date
`POST`	`/subscriptions/pause`	Pause — the renewal executor refuses to charge until resumed
`POST`	`/subscriptions/resume`	Resume (re-anchors a past-due next-charge date one interval out, never firing a missed-cycle backlog)
`POST`	`/subscriptions/cancel`	Cancel — terminal
`POST`	`/subscriptions/renew`	Fire a due renewal: charge the mandate, mint the reorder’s checkout link, advance the schedule

Fire a due renewal — the subscription snapshot, the mandate it draws on, and the checkout config (hosted link base URL + merchant). interval is one of weekly, biweekly, monthly, quarterly; channel is whatsapp or rcs.

curl -X POST https://api.orbit.devotel.io/api/v1/commerce/subscriptions/renew \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription": { "id": "sub_abc123", "...": "the snapshot returned by /subscriptions" },
    "mandate": { "id": "mnd_abc123", "...": "the snapshot returned by /agent-mandate" },
    "config": {
      "hostedBaseUrl": "https://pay.example.com/checkout",
      "merchant": "store.example.com"
    }
  }'

Success — mandate charged for the cycle, reorder checkout link minted, schedule advanced, and a commerce.subscription.renewed webhook payload returned for you to dispatch:

{
  "data": {
    "subscription": {
      "id": "sub_abc123",
      "status": "active",
      "cyclesCompleted": 3,
      "nextChargeAt": 1787520000000
    },
    "mandate": { "id": "mnd_abc123", "status": "active", "spent": 149.97 },
    "checkout": {
      "checkoutId": "sub_abc123-renewal-3",
      "hostedUrl": "https://pay.example.com/checkout/sub_abc123-renewal-3"
    },
    "webhookEvent": {
      "event": "commerce.subscription.renewed",
      "subscriptionId": "sub_abc123",
      "cycleNumber": 3,
      "amount": 49.99,
      "currency": "USD",
      "channel": "whatsapp",
      "chargeReference": "sub_abc123-cycle-3"
    }
  },
  "meta": { "request_id": "req_6b7c8d9e", "timestamp": "2026-08-26T00:00:00.000Z" }
}

Renewing a paused (or not-yet-due) subscription is refused with a 422 VALIDATION_ERROR — the pause gate exists so a renewal can fire only an explicit, consented charge:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "cannot renew a subscription in status \"paused\""
  },
  "meta": { "request_id": "req_f0a1b2c3", "timestamp": "2026-08-26T00:00:00.000Z" }
}

The schedule is left untouched on any refusal, so you can retry after resume or a mandate fix.

API Reference

All Endpoints

Commerce API: cart, checkout, and pay-by-link

Commerce API

Using the SDKs

Cart & checkout

Hosted pay-by-link

In-thread channel checkout

Agent payment mandates

Metered agent-to-agent sessions (MPP)

Direct carrier billing (DCB)

AI-shopping-agent storefronts (ACP / UCP)

Subscriptions

See also

​Commerce API

​Using the SDKs

​Cart & checkout

​Hosted pay-by-link

​In-thread channel checkout

​Agent payment mandates

​Metered agent-to-agent sessions (MPP)

​Direct carrier billing (DCB)

​AI-shopping-agent storefronts (ACP / UCP)

​Subscriptions

​See also

Commerce API

Using the SDKs

Cart & checkout

Hosted pay-by-link

In-thread channel checkout

Agent payment mandates

Metered agent-to-agent sessions (MPP)

Direct carrier billing (DCB)

AI-shopping-agent storefronts (ACP / UCP)

Subscriptions

See also