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

> ## Agent Instructions
> Sapiom is for platforms whose agent shops for many users. Each user has their own Sapiom user key and saved cards.
> Use the user's key for every call made on that user's behalf. Never use one user's key for another user, and never give the agent the platform key.
> Backends call the REST API at https://api.sapiom.ai/v1. Agents can also call the hosted MCP tools at https://api.sapiom.ai/v1/mcp/pay. Both take the key in an x-api-key header.
> Keys that start with sk_test_ reach the sandbox, a separate environment with its own users and cards, at the same addresses. Use test card numbers only there.
> Never ask a user for a card number, expiry date or CVV in chat. Users enter card details only on Sapiom's hosted pages.
> Check the merchant before buying. Use purchase.type ucp_checkout only when the merchant check returns supported. Otherwise use browser_checkout.
> Follow the nextAction in each transaction result. Action links are secrets. Send each one only to the person `nextAction.actor` names.
> Use one idempotency key per transaction. Resume an unanswered create with the same request and key. If a UCP update or cancellation is uncertain, stop and hand off to a person. If a browser cancellation is uncertain, read the transaction and resend the same cancellation, with the same key, only if it is not closed. Never start a new transaction to escape an uncertain outcome.
> For a ucp_checkout purchase, report an order as placed only when order.outcome is confirmed; if it is unknown, stop and hand off to a person. A browser_checkout purchase has no order confirmation (order is null): confirm the order on the merchant's page.

# Budgets and spending limits

> Build trust by letting users stay in control of their agent spend

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](https://docs.sapiom.ai/cards/add-a-card.md) 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](https://mintcdn.com/sapiom-1f975ca2/9get71X2H3eNyHfD/images/wayfare/set-a-budget-network.jpg?fit=max\&auto=format\&n=9get71X2H3eNyHfD\&q=85\&s=c2d33fb14ab852da4b8580fca4630f75)

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](https://mintcdn.com/sapiom-1f975ca2/9get71X2H3eNyHfD/images/wayfare/set-a-budget-card-number.jpg?fit=max\&auto=format\&n=9get71X2H3eNyHfD\&q=85\&s=6db01986fb4f64eade3371cc3a08cb20)

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](https://mintcdn.com/sapiom-1f975ca2/9get71X2H3eNyHfD/images/wayfare/visa-confirm-budget.png?fit=max\&auto=format\&n=9get71X2H3eNyHfD\&q=85\&s=cf30deaacb9c0e560c629be6c8b4b5a8)

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](https://mintcdn.com/sapiom-1f975ca2/9get71X2H3eNyHfD/images/wayfare/budget-confirmed.jpg?fit=max\&auto=format\&n=9get71X2H3eNyHfD\&q=85\&s=89295a7888d302f92082f712cc71dbc1)

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`:

```bash theme={null}
curl "https://api.sapiom.ai/v1/payment-cards/$CARD_ID" \
  -H "x-api-key: $SAPIOM_USER_KEY"
```

### 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:

```bash theme={null}
curl "https://api.sapiom.ai/v1/payment-cards/$CARD_ID/budget-links" \
  -H "x-api-key: $SAPIOM_USER_KEY" -H "Content-Type: application/json" \
  -d '{"budget":{"amount":{"value":"50.00","currency":"USD"}}}'
# Send the user the "url". Leave out "budget" to let them enter the amount.
```

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

| Limit | Caps |
| - | - |
| `purchaseLimit` | Each purchase |
| `recurringLimit` | Total spend per UTC `week`, `month` or `year` |
| `customLimit` | Total spend between two UTC dates (`startDate`, `endDate`) |

Set limits with an API key from **Create key** in the dashboard's [API keys](https://app.sapiom.ai/dashboard/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`:

```bash theme={null}
curl "https://api.sapiom.ai/v1/payment-cards/$CARD_ID/spending-limits" \
  -H "x-api-key: $SAPIOM_ORG_KEY" -H "sapiom-tenant: $USER_ID"
```

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:

```bash theme={null}
curl -X PUT "https://api.sapiom.ai/v1/payment-cards/$CARD_ID/spending-limits" \
  -H "x-api-key: $SAPIOM_ORG_KEY" -H "sapiom-tenant: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"version":3,"purchaseLimit":{"amount":"100.00","currency":"USD"},"recurringLimit":{"amount":"500.00","currency":"USD","period":"month"},"customLimit":null}'
```

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](https://docs.sapiom.ai/api-reference/mcp-tools.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.