> ## 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. # Set spending limits > Replaces a card's spending limits. Send the `version` from [Get spending limits](/api-reference/spending-limits/get-spending-limits), or `0` the first time, and `null` for any limit you don't want. Returns `409` when that version is out of date or the card can't be used. Requires a key with `org.read` to read limits or `org.write` to set them, such as your [platform key](/api-reference/overview#authentication), and the buyer's ID in the `sapiom-tenant` header. Buyer keys have neither permission. ## OpenAPI ````yaml /api-reference/openapi.json put /v1/payment-cards/{cardId}/spending-limits openapi: 3.0.0 info: title: Sapiom Pay API version: '1.0' description: >- Create buyers, save their cards and authorize transactions. Send your platform key or a buyer key in the `x-api-key` header. servers: - url: https://api.sapiom.ai description: Production security: - api-key: [] tags: - name: Buyers description: One buyer per end user. Called tenants in the API. - name: Cards description: Hosted card setup links and the buyer's saved cards. - name: Spending limits description: Limits on what each card can spend. - name: Merchants description: Check whether Sapiom can buy from a merchant. - name: Transactions description: Create a transaction and drive its UCP checkout. - name: Browser checkout description: Placeholder cards and the relay Browser Pay uses. paths: /v1/payment-cards/{cardId}/spending-limits: put: tags: - Spending limits summary: Set spending limits description: >- Replaces a card's spending limits. Send the `version` from [Get spending limits](/api-reference/spending-limits/get-spending-limits), or `0` the first time, and `null` for any limit you don't want. Returns `409` when that version is out of date or the card can't be used. Requires a key with `org.read` to read limits or `org.write` to set them, such as your [platform key](/api-reference/overview#authentication), and the buyer's ID in the `sapiom-tenant` header. Buyer keys have neither permission. operationId: CardLimitsController_set parameters: - name: cardId required: true in: path schema: type: string - name: sapiom-tenant in: header required: true schema: type: string description: >- The buyer's ID: the `id` from [Create a buyer](/api-reference/buyers/create-a-buyer). requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - version - purchaseLimit - recurringLimit - customLimit properties: version: type: integer minimum: 0 maximum: 2147483646 description: Current saved version; 0 for first configuration. purchaseLimit: type: object additionalProperties: false required: - amount - currency properties: amount: type: string pattern: ^(0|[1-9]\d{0,17})(\.\d{1,2})?$ example: '100.00' description: >- Positive USD decimal amount; at most two fractional digits. currency: type: string enum: - USD nullable: true recurringLimit: type: object additionalProperties: false required: - amount - currency - period properties: amount: type: string pattern: ^(0|[1-9]\d{0,17})(\.\d{1,2})?$ example: '100.00' description: >- Positive USD decimal amount; at most two fractional digits. currency: type: string enum: - USD period: type: string enum: - week - month - year nullable: true customLimit: type: object additionalProperties: false required: - amount - currency - startDate - endDate properties: amount: type: string pattern: ^(0|[1-9]\d{0,17})(\.\d{1,2})?$ example: '100.00' description: >- Positive USD decimal amount; at most two fractional digits. currency: type: string enum: - USD startDate: type: string format: date description: UTC calendar date, inclusive. endDate: type: string format: date description: UTC calendar date, inclusive. nullable: true responses: '200': description: '' content: application/json: schema: type: object additionalProperties: false required: - version - purchaseLimit - recurringLimit - customLimit - ruleId - status - evaluatedAt - configurationActive - additionalLimits - usage properties: version: type: integer minimum: 0 maximum: 2147483646 description: Current saved version; 0 for first configuration. purchaseLimit: type: object additionalProperties: false required: - amount - currency properties: amount: type: string pattern: ^(0|[1-9]\d{0,17})(\.\d{1,2})?$ example: '100.00' description: >- Positive USD decimal amount; at most two fractional digits. currency: type: string enum: - USD nullable: true recurringLimit: type: object additionalProperties: false required: - amount - currency - period properties: amount: type: string pattern: ^(0|[1-9]\d{0,17})(\.\d{1,2})?$ example: '100.00' description: >- Positive USD decimal amount; at most two fractional digits. currency: type: string enum: - USD period: type: string enum: - week - month - year nullable: true customLimit: type: object additionalProperties: false required: - amount - currency - startDate - endDate properties: amount: type: string pattern: ^(0|[1-9]\d{0,17})(\.\d{1,2})?$ example: '100.00' description: >- Positive USD decimal amount; at most two fractional digits. currency: type: string enum: - USD startDate: type: string format: date description: UTC calendar date, inclusive. endDate: type: string format: date description: UTC calendar date, inclusive. nullable: true ruleId: type: string format: uuid nullable: true status: type: string enum: - active - paused - removed evaluatedAt: format: date-time type: string configurationActive: type: boolean description: >- Effective configuration exists; each proposed purchase still must pass all applicable limits. additionalLimits: type: array description: >- Other matching or conditional payment rules. Managed through Rules; excluded from these settings slots. items: type: object additionalProperties: false required: - ruleId - constraintId - name - scope - limit - groupBy - usage properties: ruleId: format: uuid type: string constraintId: format: uuid type: string name: type: string scope: type: string enum: - match - unavailable limit: type: object additionalProperties: false required: - kind - amount - currency properties: kind: type: string enum: - money amount: type: string currency: type: string enum: - USD groupBy: type: array items: type: string enum: - agent - trace - service - paymentCardId usage: type: object additionalProperties: false required: - available - state - currency - startInclusive - endExclusive - resetAt - spent - pendingCommitted - used - remaining properties: available: type: boolean state: type: string enum: - active - future - expired - inactive - unavailable currency: type: string enum: - USD startInclusive: type: string format: date-time nullable: true endExclusive: type: string format: date-time nullable: true resetAt: type: string format: date-time nullable: true spent: type: string nullable: true description: >- Decimal USD amount, or null when evidence is unavailable. pendingCommitted: type: string nullable: true description: >- Decimal USD amount, or null when evidence is unavailable. used: type: string nullable: true description: >- Decimal USD amount, or null when evidence is unavailable. remaining: type: string nullable: true description: >- Decimal USD amount, or null when evidence is unavailable. nullable: true usage: type: object additionalProperties: false properties: purchaseLimit: type: object nullable: true description: Always null when this slot is present. recurringLimit: type: object additionalProperties: false required: - available - state - currency - startInclusive - endExclusive - resetAt - spent - pendingCommitted - used - remaining properties: available: type: boolean state: type: string enum: - active - future - expired - inactive - unavailable currency: type: string enum: - USD startInclusive: type: string format: date-time nullable: true endExclusive: type: string format: date-time nullable: true resetAt: type: string format: date-time nullable: true spent: type: string nullable: true description: >- Decimal USD amount, or null when evidence is unavailable. pendingCommitted: type: string nullable: true description: >- Decimal USD amount, or null when evidence is unavailable. used: type: string nullable: true description: >- Decimal USD amount, or null when evidence is unavailable. remaining: type: string nullable: true description: >- Decimal USD amount, or null when evidence is unavailable. customLimit: type: object additionalProperties: false required: - available - state - currency - startInclusive - endExclusive - resetAt - spent - pendingCommitted - used - remaining properties: available: type: boolean state: type: string enum: - active - future - expired - inactive - unavailable currency: type: string enum: - USD startInclusive: type: string format: date-time nullable: true endExclusive: type: string format: date-time nullable: true resetAt: type: string format: date-time nullable: true spent: type: string nullable: true description: >- Decimal USD amount, or null when evidence is unavailable. pendingCommitted: type: string nullable: true description: >- Decimal USD amount, or null when evidence is unavailable. used: type: string nullable: true description: >- Decimal USD amount, or null when evidence is unavailable. remaining: type: string nullable: true description: >- Decimal USD amount, or null when evidence is unavailable. '409': description: Stale version or unavailable card security: - api-key: [] components: securitySchemes: api-key: type: apiKey in: header name: x-api-key description: >- Your platform key for buyer management, or a buyer key for everything else. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.