> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Commerce hub: mandates, subscriptions, AI storefront

> Operate the three Commerce hub consoles — the agent-mandate ledger (issue/authorize/charge/verify/revoke scoped, spend-capped AI-agent consent), the subscription schedule (start off a cart, pause/resume/cancel, renew over RCS/WhatsApp), and the agent-facing ACP storefront (publish the catalog third-party shopping agents discover).

# 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](/guides/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](#1-agent-mandate-ledger)
2. [Manage subscriptions](#2-subscriptions)
3. [Publish the AI storefront](#3-storefront)
4. [Check console-vs-API parity](#4-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:

| Console surface      | API endpoints it drives                                                                                                                                                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Agent-mandate ledger | `/commerce/agent-mandate` issue · `/commerce/agent-mandate/authorize` · `/commerce/agent-mandate/charge` · `/commerce/agent-mandate/verify` · `/commerce/agent-mandate/revoke` · `/commerce/agent-mandate/network-token` |
| Subscriptions        | `/commerce/subscriptions` create · pause · resume · cancel · renew                                                                                                                                                       |
| Storefront           | `GET /commerce/agentic/storefront` · `PUT /commerce/agentic/storefront`                                                                                                                                                  |

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

* [Conversational Commerce Checkout](/guides/conversational-commerce-checkout) — the end-to-end purchase flow these consoles operate on, and the "go further" section that names `/agentic/*` and `/subscriptions/*`
* [Commerce API reference](/api-reference/commerce) — every endpoint and field
* [WhatsApp channel](/channels/whatsapp) — the subscription renewal/checkout surface
* [RCS channel](/channels/rcs) — the other renewal/checkout surface