# Purchase credits

`POST /v1/organizations/{organization}/billingAccount/purchase-credits`, operation `billingAccounts.PurchaseCredits`

Starts a purchase of credits, paid with a card in Stripe Checkout.

The caller's browser goes to the purchase's checkoutUri to pay, and comes back to returnUri. Its credits are granted once Stripe says it is paid. A suspended billing account buys none, which fails with failed_precondition and the reason ACCOUNT_SUSPENDED.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `organization` | path | Yes | `string` | The organization's ID. |

## Request body

Content-Type: `application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | `Money` | Yes | The credits to buy, in US dollars and whole cents, from $10 to $200; Stripe adds any tax. |
| `amount.currencyCode` | `string` | Yes | The currency, as its three-letter ISO 4217 code, such as USD. |
| `amount.nanos` | `integer (int32)` | Yes | The billionths of a unit of the amount, such as 500000000 of US$1.50. |
| `amount.units` | `integer (int64)` | Yes | The whole units of the amount, such as 1 of US$1.50. |
| `autoReload` | `boolean` | No | Whether to save the card for auto-reload, and turn it on once paid. |
| `returnUri` | `string (uri)` | Yes | Where Stripe sends the browser back, paid or not: a page of the console. Once paid, it has the query parameter purchase added, the purchase's ID. |

## Responses

### 201

Created

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | `Money` | Yes | The credits it buys, before any tax; once paid, what Stripe charged. |
| `amount.currencyCode` | `string` | Yes | The currency, as its three-letter ISO 4217 code, such as USD. |
| `amount.nanos` | `integer (int32)` | Yes | The billionths of a unit of the amount, such as 500000000 of US$1.50. |
| `amount.units` | `integer (int64)` | Yes | The whole units of the amount, such as 1 of US$1.50. |
| `checkoutUri` | `string` | Yes | Stripe's page to pay at, while it is open. |
| `createTime` | `string (date-time)` | Yes | When it was started. |
| `creditGrant` | `string` | Yes | The credits it bought, organizations/{organization_id}/creditGrants/{credit_grant_id}, once paid. |
| `expireTime` | `string (date-time)` | No | When the checkout stops taking a payment, while it is open. |
| `failure` | `string` | Yes | Why the card's bank declined it, once failed. |
| `invoiceUri` | `string` | Yes | The invoice that Stripe hosts for it, once paid and Stripe has finalized it. |
| `kind` | `string` | Yes | How it is paid for: CHECKOUT, in Stripe Checkout, by whoever started it; AUTO_RELOAD, by auto-reload, with the saved card. Values: `CHECKOUT`, `AUTO_RELOAD`. |
| `name` | `string` | Yes | Resource name, organizations/{organization_id}/purchases/{purchase_id}. |
| `receiptUri` | `string` | Yes | Stripe's receipt for an auto-reload, once paid. |
| `state` | `string` | Yes | Where it stands: OPEN, waiting to be paid at checkoutUri; PAID, and its credits granted; EXPIRED, the checkout ended without a payment; FAILED, the card's bank declined an auto-reload; DISPUTED, paid, then disputed, and what was left of its credits taken back. Values: `OPEN`, `PAID`, `EXPIRED`, `FAILED`, `DISPUTED`. |
| `updateTime` | `string (date-time)` | Yes | When it last changed, such as when it was paid. |

### default

Error

Base URL: `https://api.kosem.ai`. See [API conventions](https://docs.kosem.ai/reference/api-conventions.md) for authentication, pagination and errors, and [https://docs.kosem.ai/openapi.yaml](https://docs.kosem.ai/openapi.yaml) for the full OpenAPI document.