Skip to main content
The Macropay MCP server 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 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.
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.

​
What the agent can do

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.
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.

​
Turn it on

1

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.
2

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, grant it checkouts:write and events:write.
3

Ask your agent to transact

Once connected, prompt naturally:
“Create a checkout for product prod_… for 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.

​
Examples

Bill a lead in one sentence
“Generate a Pro-plan checkout for 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 and 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.
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 and usage-based billing.
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.