---
title: "Purchase Reload"
method: POST
path: "/api/v1/billing/reloads"
tags: ["billing"]
---

# Purchase Reload

`POST /api/v1/billing/reloads`

Buy one approved bundle now, on the saved card.

``Idempotency-Key`` is required because this charges immediately. A
client that lost the response retries with the same key and is handed the
attempt it already made rather than a second charge.

Usage is added when the payment succeeds, which is usually before this
returns. A decline comes back as a ``failed`` attempt, not an error. When
the bank wants the customer present, the attempt is ``requires_action``
and ``confirmation_url`` is where to send the browser.

## Headers

- `Idempotency-Key` string, required

## Request body

- ReloadPurchaseRequest — Buy one approved bundle now.
  - `bundle_usd` union, required
    - number
    - string

## Response `200`

Successful Response

- ReloadPurchaseResponse — The attempt a purchase or confirmation produced. ``confirmation_url`` is present when the bank wants the customer present: send the browser there, and Stripe returns it to the billing page when the payment is confirmed. The balance moves when the payment does, and the client hears about it on the usual refresh event.
  - `attempt` ReloadAttemptView, required — One reload attempt as a workspace sees it.
    - `id` string, uuid, required
    - `trigger` 'manual' | 'automatic', required — Who started a reload.
    - `status` 'pending' | 'requires_action' | 'succeeded' | 'failed' | 'canceled', required — Where one attempt stands, as read back from its PaymentIntent.
    - `amount_usd` string, required
    - `failure_code` 'authentication_required' | 'card_declined' | 'no_saved_payment_method' | 'not_charged' | 'payment_failed', required — Why an attempt ended without collecting, in customer-actionable terms.
    - `created_at` string, date-time, required
    - `resolved_at` string, date-time, nullable, required
  - `confirmation_url` string, nullable, required

## Other responses

- `409` — Conflict
- `422` — Validation Error
- `503` — Service Unavailable

## Changes

- **2026-09-19** `924eeadc29ad` — 2 warning
  - added the new `amount_not_positive` enum value to the `code` response property for the response status `409`
  - added the new `terms_incomplete` enum value to the `code` response property for the response status `409`
- **2026-09-18** `73f618ba0a7e` — 1 warning
  - added the new `price_not_found` enum value to the `code` response property for the response status `503`
- **2026-09-16** `95495ef535bc` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/maia-analytics/apis/maia-api/changes/api/v1/billing/reloads/post.md)

---

[API](https://skmtc.dev/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.dev/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/maia-analytics/apis/maia-api/revisions/8dc47faf0418?raw)