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

# Manage buyers

> Create a buyer and buyer key for each of your users, handle buyers that already exist, store keys safely and remove buyers.

Each user who buys through your agent needs their own Sapiom buyer and buyer key. This page covers setting them up for real users from your backend. To try it once with a test user, see the [quickstart](https://docs.sapiom.ai/quickstart.md). In the API, a buyer is called a tenant.

**You need:** your platform key, kept in your backend. Never give it to your agent.

## When to create a buyer

Create a buyer and key once per user, the first time they need one: when they sign up, or when they first ask your agent to buy something. Reuse both after that.

## Create the buyer

Use your own ID for the user as `externalId`. It links the Sapiom buyer to your user, so the same person never gets two buyers.

```bash theme={null}
curl https://api.sapiom.ai/v1/tenants \
  -H "x-api-key: $SAPIOM_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","externalId":"user_123"}'
```

Store the returned `id` with your user record. The next examples call it `BUYER_ID`.

### If the buyer already exists

`409 Conflict` means a buyer with that `externalId` already exists, for example after a retry. Look it up instead of creating another:

```bash theme={null}
curl "https://api.sapiom.ai/v1/tenants?filter%5BexternalId%5D=user_123" \
  -H "x-api-key: $SAPIOM_PLATFORM_KEY"
```

## Create and store the buyer key

```bash theme={null}
curl "https://api.sapiom.ai/v1/tenants/$BUYER_ID/api-keys" \
  -H "x-api-key: $SAPIOM_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"user_123"}'
```

The response includes `plainKey`, shown only once. Store it encrypted with your user record and reuse it for every session with that user. Your backend passes it to your agent and browser worker for that session. See [Connect your agent](https://docs.sapiom.ai/buyers/connect-agent.md).

## Remove a buyer

To remove a buyer, for example when a user closes their account, call `DELETE /v1/tenants/{BUYER_ID}` with your platform key.


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