Skip to main content
Budgets are set on cards, have time limits, and are reported to the card-issuing networks. They are required for autonomous spending. Spending limits optional, and are more flexible. Set them on a user’s behalf by default or based on their preference.

Budgets

A budget is how much your agent can spend with one of a user’s cards over the next 30 days. The user sets it on a page with your brand, and you can propose the amount. Within the budget, purchases go straight to payment, without asking the user.

How a user sets a budget

Right after the user adds a card, the setup page asks for a budget. Send budget.amount in the setup link to propose an amount, or leave it out to let the user enter one.
Set a budget page for Wayfare: up to $50.00 for 30 days on Visa ending in 4242, with Confirm with Visa and Skip for now

The card's network can verify the budget

Set a budget page for Wayfare: up to $50.00 for 30 days on Visa ending in 0119, paid with the card number, with Set budget and Skip for now

Card number only

When the card’s network can verify the budget, the user confirms it with the network, for example with a Visa passkey. The network then knows the budget, and purchases can be paid with a network agentic token or the card number. Otherwise the user clicks Set budget, and purchases are paid with the card number. Either way, the user’s security code is saved with the budget, so purchases within it don’t ask for it.
Visa's window asking the user to confirm $100.00 with a passkey

Confirming with Visa

Budget confirmed page for Wayfare: your agent can spend up to $50.00 on Visa ending in 4242 until December 16, 2026

Budget confirmed

Without a budget, each purchase waits for the user’s security code. Skip for now leaves the card without one.

Check a card’s budget

Read the card. Its budget shows the amount, what is available, expiresAt and status:

When a budget runs out

A budget lasts 30 days and doesn’t refill; a new budget starts a new 30 days. A purchase over what is left, or after the budget ends, is refused with budget_insufficient or budget_expired, with available and expiresAt; nothing is charged. To renew a budget, send the user a budget link. They enter the amount and their security code, confirm, and the new budget replaces the old one:

What a budget covers

Budgets cover every purchase on a user’s card, at any merchant, on any checkout type, with any credential. Each card has one budget. A purchase uses one card: paymentCardId, or the user’s default. Budgets are never pooled and a purchase is never split. Canceling a purchase before payment releases its hold; spent stays spent. Budgets are in USD; a purchase in another currency counts at its USD equivalent, at the ECB rate stored with it.

Spending limits

Spending limits are caps you set on a user’s card. A purchase over any limit is denied. Limits don’t change whether the user is asked: they cap spend inside or outside a budget, and the agent can’t raise them. Set limits with an API key from Create key in the dashboard’s API keys, naming the user in the sapiom-tenant header. A platform key from Create platform key can’t read or set limits. Read the card’s limits first, for their version and usage:
Then set all three with that version (0 the first time). null removes a limit, and 409 RULE_VERSION_CONFLICT means they changed since you read them:
Refunds don’t restore a limit’s capacity, and changing a limit’s period resets its usage. An agent on the MCP server at https://api.sapiom.ai/v1/mcp can read and set limits with sapiom_get_card_spending_limits and sapiom_set_card_spending_limits. See the MCP tools reference.