Skip to main content
POST
Start a credit purchase

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

Optional key that makes retries safe. Reusing the same key returns the existing purchase instead of starting a second charge.

Keys are scoped to the account and this operation, can be up to 255 characters, and should be treated as permanently used. If the header is missing or empty, replay protection is disabled.

Body

application/json
amount
integer<int64>
required

Amount in cents to purchase. Must be a positive integer, and cannot exceed the credit balance cap.

Required range: 1 <= x <= 50000

Response

The purchase attempt that was started.

id
string
required

Unique identifier for this credit purchase attempt.

status
enum<string>
required

Current state of the purchase. Poll GET until it reaches a terminal state (succeeded or failed).

An asynchronous webhook records succeeded and actionRequired, and a periodic sweep backstops a lost webhook. A purchase can therefore stay pending until the next sweep runs, after the charge itself settles.

Available options:
pending,
actionRequired,
succeeded,
failed
amountCents
integer<int64>
required

Amount purchased, in cents.

currency
string
required

ISO 4217 currency code, lowercase.

createdAt
string<date-time>
required

When the purchase attempt was started.

expiresAt
string<date-time>
required

When the purchased credits stop being usable.

failureCode
string | null

Machine-readable decline reason. Set when status is failed, and also set to ambiguous_upstream while status is pending if a prior attempt's outcome could not be determined.

failureMessage
string | null

Human-readable decline detail, set only when status is failed.