> ## 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 Pay is for platforms whose agent shops for many end users. Each end user is a buyer with their own Sapiom key and saved cards.
> Use the buyer's key for every call made on that buyer's behalf. Never use one buyer's key for another user, and never give the agent the platform key.
> Agents call the hosted MCP tools at https://api.sapiom.ai/v1/mcp. Backends call the REST API at https://api.sapiom.ai/v1. Both take the key in an x-api-key header.
> Never ask a buyer for a card number, expiry date or CVV in chat. Buyers enter card details only on Sapiom's hosted pages.
> Follow the nextAction in each transaction result. Action links are secrets for the intended buyer only.
> Use one idempotencyKey per transaction. After a timeout, retry with the same key. Never start a new transaction to escape an uncertain outcome.
> Report an order as placed only when order.outcome is confirmed. If it is unknown, stop and hand off to a person.

# Cap what a buyer's card can spend

> Set per-transaction, per-period and date-range limits on a buyer's saved card.

Spending limits cap what a buyer's card can spend. A transaction must fit every limit on its card, and limits work alongside the buyer's approval, never instead of it. A card doesn't need limits to pay.

**You need:** your [platform key](https://docs.sapiom.ai/api-reference/overview.md#authentication), with the buyer's ID in the `sapiom-tenant` header. Buyer keys can't change limits, so your agent can't raise one to get past a denial.

## Limit types

Each card has three optional limits. Amounts are decimal strings, such as `"100.00"`, and `currency` is `USD`.

| Limit | Shape | Caps |
| - | - | - |
| `purchaseLimit` | `{ amount, currency }` | Each transaction |
| `recurringLimit` | `{ amount, currency, period }` | Total spend per `week`, `month` or `year` |
| `customLimit` | `{ amount, currency, startDate, endDate }` | Total spend between two UTC dates, inclusive (`YYYY-MM-DD`) |

## Read a card's limits

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

Returns the three limits, the saved `version`, and `usage`, which shows what the period and date-range limits have `used` and have `remaining`.

## Set limits

Setting replaces all three limits. Send each one, with `null` for any you don't want, and the `version` you read (`0` the first time):

```bash theme={null}
curl -X PUT "https://api.sapiom.ai/v1/payment-cards/$CARD_ID/spending-limits" \
  -H "x-api-key: $SAPIOM_PLATFORM_KEY" \
  -H "sapiom-tenant: $BUYER_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}'
```

* `409` with `RULE_VERSION_CONFLICT` means the limits changed since you read them. Read again, then set.
* `409` with `CARD_UNAVAILABLE` means the card isn't ready yet.
* Changing a period or date-range limit starts a fresh allowance. Saving it unchanged keeps what has been used.
* A merchant refund or cancellation doesn't restore spending capacity.

| Task | API | MCP tool |
| - | - | - |
| Read limits | [`GET /v1/payment-cards/{cardId}/spending-limits`](https://docs.sapiom.ai/api-reference/spending-limits/get-spending-limits) | `sapiom_get_card_spending_limits` |
| Set limits | [`PUT /v1/payment-cards/{cardId}/spending-limits`](https://docs.sapiom.ai/api-reference/spending-limits/set-spending-limits) | `sapiom_set_card_spending_limits` |


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