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

# Agentic Commerce via MCP

> Let a connected AI agent act on your billing — create checkouts and record usage — not just read it. Off by default, opt-in per organization.

The [Macropay MCP server](/features/integrations/mcp) already lets a connected AI
client **read** your billing: "what's my MRR?", "who churned this month?", "is
acme entitled to the API tier?". **Agentic commerce** adds the other half — letting
the agent **act**:

> *"Create a checkout for the Pro plan for [jane@acme.com](mailto:jane@acme.com) and give me the link."*
>
> *"Record 5,000 tokens of usage for acme on the gpt-4o meter."*

It turns the MCP connection from a read-only analytics surface into an operational
billing copilot — you run Macropay by talking to your AI, and an autonomous agent
can transact on your behalf.

<Note>
  Agentic commerce is **off by default** and enabled **per organization**. Turning
  it on is a deliberate trust decision: it lets a connected agent create real
  checkout links and record billable usage.
</Note>

## What the agent can do

| Tool              | What it does                                                                                                                                            | Scope required    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `create_checkout` | Creates a hosted checkout link for a product and returns the URL the customer pays at. Optionally pre-fills the customer email and overrides the price. | `checkouts:write` |
| `record_usage`    | Records a usage/metering event for a customer (for usage-based billing). The quantity goes in the event metadata; the meter aggregates per its config.  | `events:write`    |

Reads an agent might pair with these — customer **entitlements/state**, products,
subscriptions, revenue — are already available through the standard MCP tools and
need no opt-in.

<Warning>
  The agent never touches a card. `create_checkout` returns a **hosted** Macropay
  checkout URL; the customer enters payment details on Macropay's PCI-compliant
  page. The agent can create the link, not charge a card directly.
</Warning>

## Turn it on

<Steps>
  <Step title="Enable it for your organization">
    In the dashboard, go to **Settings → Integrations → MCP** and toggle on
    **Agentic commerce → Let agents transact**. This sets the
    `mcp_agentic_commerce` feature flag on your organization. It stays off for
    every other org.
  </Step>

  <Step title="Make sure the connecting token has write scopes">
    Both gates must be satisfied — the org flag **and** the access token's scopes.

    * **Claude Desktop / Cursor (OAuth):** the Macropay MCP OAuth client already
      requests `checkouts:write` and `events:write`, so reconnect (or re-authorize)
      after enabling the flag and the tools become usable.
    * **Organization Access Token (manual):** when you mint an
      [Organization Access Token](/features/integrations/mcp#manual-auth-organization-access-token),
      grant it `checkouts:write` and `events:write`.
  </Step>

  <Step title="Ask your agent to transact">
    Once connected, prompt naturally:

    > *"Create a checkout for product `prod_…` for [jane@acme.com](mailto:jane@acme.com)."*

    The agent calls `create_checkout` and hands you back the hosted URL. If the
    org flag is off (or the token lacks the scope), the tool returns a clear
    message telling you what to enable — it never silently no-ops.
  </Step>
</Steps>

## Examples

**Bill a lead in one sentence**

> *"Generate a Pro-plan checkout for [jane@acme.com](mailto:jane@acme.com) and DM me the link."*

`create_checkout(product_id="prod_pro", customer_email="jane@acme.com")` →
`{ "url": "https://checkout.macropay.ai/…", "id": "checkout_…", "status": "open" }`

**Meter autonomous-agent usage**

> *"Record 5,000 tokens of usage for customer acme on the gpt-4o meter, attributed
> to agent ag\_7."*

`record_usage(event_name="gpt-4o", customer_id="cus_acme", agent_id="ag_7",
metadata={"tokens": 5000})` → `{ "inserted": 1, "duplicates": 0 }`

The event flows into the same metering pipeline as the
[Events API](/api-reference/events/ingest-events) and
[usage-based billing](/features/usage-based-billing), so it shows up on the meter,
the customer's usage, and your revenue exactly like any other ingested event.

## Function reference

### `create_checkout`

Creates a hosted Macropay checkout session for a product and returns the URL the
customer pays at. Wraps `POST /v1/checkouts/` — see the
[Create Checkout Session](/api-reference/checkouts/create-session) API reference.

```text theme={null}
create_checkout(product_id, customer_email?, success_url?, amount?)
```

| Parameter        | Type          | Required | Description                                                                      |
| ---------------- | ------------- | -------- | -------------------------------------------------------------------------------- |
| `product_id`     | string (UUID) | yes      | The product to sell.                                                             |
| `customer_email` | string        | no       | Pre-fills the buyer's email on the checkout.                                     |
| `success_url`    | string        | no       | Where to send the buyer after payment. Supports the `{CHECKOUT_ID}` placeholder. |
| `amount`         | integer       | no       | Price override in **minor units** (cents), for pay-what-you-want products.       |

**Returns** `{ id, url, status, client_secret }` — give the `url` to the customer.
Requires the org's `mcp_agentic_commerce` flag **and** the `checkouts:write` scope.

### `record_usage`

Records a usage/metering event for a customer. Wraps `POST /v1/events/ingest` —
see the [Ingest Events](/api-reference/events/ingest-events) API reference and
[usage-based billing](/features/usage-based-billing).

```text theme={null}
record_usage(event_name, customer_id?, external_customer_id?, agent_id?, metadata?)
```

| Parameter              | Type          | Required | Description                                                                                                  |
| ---------------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `event_name`           | string        | yes      | The meter's event name (what the meter filters on).                                                          |
| `customer_id`          | string (UUID) | one of   | The Macropay customer id.                                                                                    |
| `external_customer_id` | string        | one of   | Your own customer id (alternative to `customer_id`). Provide **exactly one**.                                |
| `agent_id`             | string (UUID) | no       | Attributes the usage to a specific agent (agent billing).                                                    |
| `metadata`             | object        | no       | Event payload — put the metered quantity here, e.g. `{"tokens": 5000}`. The meter aggregates per its config. |

**Returns** `{ inserted, duplicates }`. Requires the org's `mcp_agentic_commerce`
flag **and** the `events:write` scope.

## Safety model

* **Two independent gates.** A tool runs only when the org flag is on **and** the
  token carries the write scope. Either alone is insufficient.
* **Real authorization, every call.** The tools dispatch through Macropay's own
  API with the connection's token, so the same scope checks, audit log, and rate
  limits that protect the REST API apply — there is no privileged side door.
* **Off by default.** Broadening the MCP OAuth client's allowed scopes does not, by
  itself, let any agent transact; nothing happens until an org admin flips the flag.
* **Revocable instantly.** Turn the flag off, or revoke the token under
  **Settings → Integrations → MCP → Connected clients**, to cut off access at once.

## Where this is heading

Agentic commerce is the foundation for fully autonomous **agent-to-agent payments**
— an agent that discovers a price, pays from a wallet, and retries, with no human in
the loop (the emerging x402 pattern). Today's `create_checkout` / `record_usage`
tools are the first, human-supervised step toward that.