Cap what a buyer's card can spend

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

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

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`	`sapiom_get_card_spending_limits`
Set limits	`PUT /v1/payment-cards/{cardId}/spending-limits`	`sapiom_set_card_spending_limits`

Get started

Buyers

Cards

Transactions

Governance

Security

Early access

Cap what a buyer's card can spend

Limit types

Read a card’s limits

Set limits

​Limit types

​Read a card’s limits

​Set limits

Limit types

Read a card’s limits

Set limits