Skip to main content

​
Commerce hub: mandates, subscriptions, AI storefront

The Commerce hub under Messages → Commerce (/messages/commerce) has three dashboards that drive the agentic-commerce endpoints directly — no cURL loop required. This guide walks each one: the agent-mandate ledger, the subscription schedule, and the AI-shopping storefront. These consoles operate the same endpoints the Conversational Commerce Checkout guide names in its “go further” section — /agent-mandate/*, /subscriptions/*, and /agentic/* — from a forms-and-buttons surface instead of raw API calls. The request shapes are identical; the console is parity, not a separate feature set. All three pages are governed the same way: only the owner, admin, and developer roles can open them. You will:
  1. Run the agent-mandate ledger
  2. Manage subscriptions
  3. Publish the AI storefront
  4. Check console-vs-API parity

​
1. Agent-mandate ledger

An agent payment mandate is a scoped, spend-capped consent under which an AI agent transacts on a buyer’s behalf. You define who the agent is (the agentId), whom it acts for (the principalId), a max per transaction, a total cap, a currency, and optional merchant/category allowlists. The agent can then authorize and charge inside those limits until you revoke it — and spend against the cap is tracked on the mandate itself. Open Messages → Commerce → Agent mandates (/messages/commerce/agent-mandate). Nothing here moves money: an authorized charge only green-lights a pay-by-link — this surface never captures funds.

​
Issue a mandate

  1. Set the Agent id, the Principal (buyer) id, and the Currency.
  2. Set Max per transaction and Total cap — the two spend bounds the server enforces on every charge.
  3. Optionally restrict the mandate with Allowed merchants and Allowed categories. Empty means any.
  4. Click Issue mandate. The mandate snapshot is the consent object; the ledger below it tracks spend against the caps.
Re-issue overwrites the open mandate with new caps/scope. Once a mandate is live you get four meters — Spent, Remaining cap, Per transaction, and Authorizations — and the status chip (active, exhausted, revoked, expired).

​
Authorize and charge

With a mandate open, the Charge under this mandate card gives you two passes over the same decision:
  • Dry-run authorize — ask “would this charge pass?” without moving the cap. The decision comes back authorized or denied, with the reason and the remaining cap. Use this to probe a limit before committing.
  • Commit charge — run the same authorization and, on a pass, advance Spent toward the cap. Every spend decision is re-derived server-side after re-checking the consent digest, so an edited snapshot can’t bypass a cap.
Both take the same inputs — amount, merchant, category — evaluated against the mandate’s caps and allowlists.

​
Verify and revoke

  • Verify integrity re-checks the mandate’s tamper-evidence digest and reports intact / tampered. Run it after any handoff of the mandate snapshot to confirm the consent you hold is the consent issued.
  • Revoke consent permanently disables the mandate — the agent can no longer authorize or charge under it. Revoke is behind a typed confirmation and cannot be undone; it’s the stop that ends an agent’s spending authority.

​
Tokenized checkout (network tokens)

Below the charge card you can present the same charge to a card network’s agentic-payment program and mint a network token in place of the hosted pay-by-link — Mastercard Agent Pay or Visa Trusted Agent Protocol. This returns a network-issued tokenized-checkout credential for the amount. If the network isn’t provisioned for your deployment it 503s; fall back to the standard commit-charge-then-pay-link path.

​
2. Subscriptions

Open Messages → Commerce → Subscriptions (/messages/commerce/subscriptions). This is the subscribe-and-save console: start a recurring subscription off an existing cart, watch the next-renewal date, and pause/resume/cancel it.

​
Start a subscription

A subscription ties a cart to a mandate and a cadence:
  1. Set the Cart id the recurring order starts from, the Buyer (principal id), and the Mandate id that will authorize each cycle.
  2. Pick the Channel — WhatsApp or RCS. Renewal checkout happens over the buyer’s channel.
  3. Set the Currency and the Interval — weekly, biweekly, monthly, or quarterly.
  4. Add the Subscribed items (SKU, quantity, unit price). At least one item is required.
  5. Click Start subscription.
Each subscription appears in the list with its status (active, paused, canceled), the amount per interval, the completed-cycle count, and its next-renewal date.

​
Pause, resume, cancel

Lifecycle is one click per state transition from the subscription row:
  • Pause (on an active subscription) — hold future charges; the subscription keeps its items and history.
  • Resume (on a paused one) — return it to active.
  • Cancel — end it. No further renewal is scheduled.

​
Renew a cycle

A renewal reuses the same payment mandate the buyer already consented to — no new consent is collected per cycle. To fire a due cycle:
  1. In the Renewal authorization card, set the Hosted checkout base URL and Merchant the reorder link points to.
  2. Paste the mandate JSON issued on the Agent payment mandates page. Renewal authorizes each cycle’s charge against this stored mandate.
  3. On an active subscription, click Renew now — Orbit authorizes the charge under the mandate and mints the reorder’s checkout over RCS/WhatsApp.

​
3. Storefront

Open Messages → Commerce → Storefront (/messages/commerce/storefront). This console publishes the storefront a third-party AI shopping agent — ChatGPT Instant Checkout, Perplexity, an AP2-style agent — discovers and drives with no Orbit credential. It’s a publish/config surface only: it decides what an agent may discover and buy; it never moves money and never sends anything.

​
Publish and merchant details

  1. Set the Merchant name and Currency (3-letter ISO, e.g. USD).
  2. Toggle Publish on. Only a published storefront is served on the public edge — keep it private while the catalog is being built.
  3. Click Publish storefront (or Save storefront while still private).
Once stored, the page shows the public storefront URL — copy it and hand it to a shopping agent. It resolves the discovery manifest plus product feed, and it’s live only while the storefront is published.

​
Categories and catalog

  • Categories — optional product categories advertised in the storefront manifest.
  • Catalog — the agent-facing product feed, up to a bounded cap per storefront. Each product has an ID, title, price, currency, availability (in_stock / out_of_stock), and optional category, link, and description. Half-typed rows are rejected on save, the same way the public edge would reject them.

​
Trusted-agent directories

Default-deny: only a verified agent signature completes a purchase unless a directory is listed here. A trusted-agent directory is a Web Bot Auth / AP2 issuer JWKS URL whose signed agents may complete a checkout on your storefront. Add a directory by ID and URL, and give it a scope — allow, deny, or rate. With none listed, only verified agents can buy; use directories to admit third-party shopping agents you trust.

​
4. Console-vs-API parity

The consoles are thin forms over the same Commerce endpoints — they neither widen nor narrow the API surface. What you can do in the UI you can do over the API, with the same request shapes: Consequences worth knowing:
  • Stateless by design. The mandate and the subscription are snapshots that you round-trip on each call — the API computes the next valid state and you persist the result. The consoles hold the snapshot in page state, which is why renewal asks you to paste the mandate JSON: the subscription page needs the consent object authorization will be checked against, the same way an API caller POSTs it in the body.
  • Same enforcement. Spend caps, allowlists, the default-deny agent trust, and catalog validation are all enforced server-side; the console can’t pass anything the API would reject.
  • Same gateway. The send/check the API returns (a minted pay-by-link, a rendered checkout) is what the console’s buttons trigger — the Commerce API produces link content; per-channel sending stays with your messaging infrastructure.

​
See also