---
title: "Buy a credit pack"
method: POST
path: "/api/v1/credits/purchases"
tags: ["Credits"]
---

# Buy a credit pack

`POST /api/v1/credits/purchases`

## Request

- Base URL: `https://app.argorant.com`
- URL: `https://app.argorant.com/api/v1/credits/purchases`
- Auth: HTTP bearer

Buys exactly what a quote showed. `confirmed: true` states that the person who pays said yes to that quote; pass their own words in `user_confirmation`. Every purchase records who confirmed it, when, through which key or connection, the amount and the quote. Buy with the same key or connection that asked for the quote; a quote from another one is refused with 409 quote_other_session. With `pay_with: auto` the saved card the owner allowed in the app is charged right away when the amount fits the owner's monthly limit and the workspace's limits; the credits are added at once and a receipt is emailed. Otherwise you get `checkout_url`, a payment page the person pays themselves; the credits arrive with that payment. The quote id makes this safe to retry: the same quote is never charged twice, and a repeat returns the first answer with `replayed: true`.

| Cost | What it does | Key scopes |
| --- | --- | --- |
| The pack price, charged only after the person who pays confirmed the quote | Charges money | `argorant:manage_lists` |

## Headers

- `Idempotency-Key` string
- `X-Request-Id` string

## Request body

- object
  - `quote_id` string, uuid, required: The quote the person said yes to.
  - `confirmed` boolean, required: true: the person who pays saw the quote and said yes.
  - `pay_with` 'auto' | 'link': auto: the saved card when allowed, else a payment link. link: always a payment link.
  - `user_confirmation` string: The person's own words that said yes to the quote, quoted exactly (up to 1,000 characters). Recorded with the purchase; without it the record says confirmed=true.
  - `price_shown_cents` integer: The price you showed the person, in cents of the quote's currency. Recorded with the purchase. A price that differs from the quote is refused with 409 price_mismatch.
  - `tool_call_id` string: The id of your tool call that carries this yes, if your app has one. Recorded with the purchase.

## Response `201`

Payment link or Paid with the saved card

- CreditPurchase
  - `purchase_id` string, uuid: Purchase id, the same as the quote id.
  - `status` 'paid' | 'awaiting_payment' | 'processing' | 'not_charged' | 'expired': paid: credits added. awaiting_payment: send checkout_url to the person who pays. processing: wait a minute. not_charged: the card was not charged. expired: the link ran out unpaid.
  - `paid_with` string, nullable: saved_card or payment_link.
  - `card` string, nullable: The saved card that was charged, for example card ending 4242.
  - `credits` integer: Credits bought.
  - `credits_added` integer: Credits added to the account.
  - `amount_cents` integer: Amount in cents.
  - `currency` string: Currency.
  - `checkout_url` string, uri, nullable: Payment page for the person who pays.
  - `message` string: What happened, in one or two sentences.
  - `saved_card` object: Present when the saved card was not used, with used (false), code and reason.
  - `replayed` boolean: Present and true when this is the answer of an earlier call with the same quote.

## Other responses

- `400`: 400 Bad request. `confirmation_required` when confirmed is not true.
- `401`: 401 Unauthorized. `unauthorized` when the API key is missing, wrong or revoked.
- `403`: 403 Forbidden. `scope_missing` when the key lacks argorant:manage_lists.
- `404`: 404 Not found. `quote_not_found` when the quote id is unknown or belongs to someone else.
- `409`: 409 Conflict. `charge_in_progress` when this quote is being charged right now; `idempotency_conflict` when the Idempotency-Key was used with another body.
- `410`: 410 Gone. `quote_expired` when the quote is older than 24 hours, or older than 15 minutes for the saved card.
- `422`: 422 Validation error. `validation_error` when a field has the wrong type or is missing.
- `429`: 429 Too many requests. `rate_limited` when too many requests this minute.

---

[API](https://skmtc.dev/argorant/apis/argorant-api.md) · [All operations](https://skmtc.dev/argorant/apis/argorant-api/llms.txt) · [OpenAPI document](https://skmtc.dev/argorant/apis/argorant-api/revisions/4bc28c0085b6?raw)