# Balance and billing

Reference for GET /v1/balance, the credit ledger, credit orders and packs, Stripe checkout, and GET /v1/workspace.

Billing data is readable with a `full` or `view` key (or the dashboard). `run` keys and agent trial keys cannot read it. Buying credits always needs a signed-in person. Amounts are whole credits, except what was paid for them (`amountUsd`) and what a credit costs (`creditPriceUsd`, `listCreditPriceUsd`). Guide: [Pricing and billing](/docs/pricing-and-billing).

## GET /v1/balance

`GET https://api.primaryapi.com/v1/balance`

Auth: API key with view or full access, or a dashboard session

| Field | Type | Description |
|---|---|---|
| `credits` | integer | Everything spendable now: bought, welcome and included credits. |
| `paidCredits` | integer | Bought credits. They never expire. |
| `promoCredits` | integer | Welcome credits, spent first. They can expire. |
| `promoExpiresAt` | string or null | When the welcome credits expire; `null` when there are none. |
| `includedCredits` | integer | Credits included with your plan, spent after welcome credits and before bought ones. Each month's credits roll over for 3 months, then expire. |
| `includedExpiry` | object or null | The next included credits due to expire, `{ credits, at }`; `null` when none are. |
| `creditPriceUsd` | number | What buying one credit costs this workspace now, in US dollars: Pay as you go's price, or its plan's price for extra credits. |

```bash
curl -sS "https://api.primaryapi.com/v1/balance" -H "Authorization: Bearer $PRIMARYAPI_VIEW_KEY"
```

```json title="200 OK"
{
  "credits": 14125,
  "paidCredits": 2500,
  "promoCredits": 25,
  "promoExpiresAt": "2027-02-07T14:05:09.120Z",
  "includedCredits": 11600,
  "includedExpiry": { "credits": 11600, "at": "2027-01-28T09:12:44.000Z" },
  "creditPriceUsd": 0.0045
}
```

## GET /v1/billing/ledger

`GET https://api.primaryapi.com/v1/billing/ledger`

Auth: API key with view or full access, or a dashboard session

Every movement of credits, newest first. Query: `limit` (1–200, default 50) and `cursor`. **200 OK**: `{ "items": [...], "nextCursor": … }` with entries:

| Field | Type | Description |
|---|---|---|
| `id` | string | Entry id. |
| `type` | string | `topup` (credits bought), `promo_grant`, `promo_expire`, `plan_grant` (credits included with a plan), `plan_expire` (included credits that reached the end of their rollover), `usage`, `usage_refund`, `refund` or `adjustment`. |
| `credits` | integer | Signed: positive adds to the balance, negative spends. |
| `balanceAfterCredits` | integer | The balance right after this entry. |
| `requestId` | string or null | The call this entry belongs to (`usage`, `usage_refund`). |
| `sku` | string or null | The API of that call. |
| `note` | string or null | A short description. |
| `createdAt` | string | ISO 8601 timestamp. |

## GET /v1/billing/orders

`GET https://api.primaryapi.com/v1/billing/orders`

Auth: API key with view or full access, or a dashboard session

Your credit purchases, newest first. Query: `limit` (1–200, default 50) and `cursor`. Each item: `{ id, credits, amountUsd, status, source, createdAt, paidAt }`, where `credits` is the number of credits bought, `amountUsd` what was (or is to be) paid, `status` is `paid`, `pending` (the payment is still clearing: a bank payment made at checkout, or an auto top-up being charged) or `failed` (it didn't go through, and nothing was charged), and `source` is `checkout` (bought in Settings → Billing), `auto` (auto top-up) or `dev` (development credits). A checkout that was opened and not finished isn't listed.

## GET /v1/billing/packs

`GET https://api.primaryapi.com/v1/billing/packs`

Auth: None

What can be bought, public:

```json title="200 OK"
{
  "packs": [2500, 10000, 25000, 100000],
  "min": 1000,
  "max": 1000000,
  "step": 100,
  "listCreditPriceUsd": 0.005,
  "checkoutEnabled": true,
  "devTopupEnabled": false
}
```

`packs` are the ready-made amounts; any other amount from `min` to `max` in steps of `step` can be bought too. `listCreditPriceUsd` is what a credit costs on Pay as you go. A workspace on a plan pays its plan's price for extra credits, shown as `creditPriceUsd` in `GET /v1/balance`.

## POST /v1/billing/checkout

`POST https://api.primaryapi.com/v1/billing/checkout`

Auth: Dashboard session only

Starts a Stripe Checkout payment for credits and returns its URL. Body: `{ "credits": 10000 }`: a pack, or any amount from 1,000 to 1,000,000 in steps of 100, charged at the workspace's credit price. **200 OK**: `{ "url": "https://checkout.stripe.com/…", "orderId": "…" }`. The credits are added when Stripe confirms the payment. API keys cannot start payments, by design. Credits are non-refundable and have no cash value; bought credits never expire.

## GET /v1/billing/auto-topup

`GET https://api.primaryapi.com/v1/billing/auto-topup`

Auth: API key with view or full access, or a dashboard session

Auto top-up and spend alerts ([how they work](/docs/pricing-and-billing#auto-top-up)):

```json title="200 OK"
{
  "enabled": true,
  "thresholdCredits": 1000,
  "amountCredits": 10000,
  "amountUsd": 45,
  "card": { "brand": "visa", "last4": "4242", "expMonth": 12, "expYear": 2030 },
  "paused": null,
  "topUpsLast24h": 1,
  "lastTopUpAt": "2026-11-09T12:00:00.000Z",
  "spendAlerts": {
    "enabled": true,
    "monthlyBudgetUsd": 100,
    "percents": [50, 80, 100],
    "spentThisMonthUsd": 45,
    "resetsAt": "2026-12-01T00:00:00.000Z"
  },
  "checkoutEnabled": true
}
```

| Field | Type | Description |
|---|---|---|
| `enabled` | boolean | Whether auto top-up buys credits when the balance falls below `thresholdCredits`. |
| `thresholdCredits` | integer | The balance that starts a top-up. |
| `amountCredits` | integer | The credits each top-up buys. |
| `amountUsd` | number | What one top-up costs at the workspace's price for credits now, in US dollars. |
| `card` | object or null | The saved card: `brand`, `last4`, `expMonth`, `expYear`. Never the card number. |
| `paused` | object or null | `{ reason, at }` while auto top-up is off because of the card: `card_declined`, `authentication_required` (the bank wants the cardholder to confirm) or `card_missing`. Turning it on again, or saving a new card, clears it. |
| `topUpsLast24h` | integer | Top-ups in the last 24 hours (at most 10). |
| `lastTopUpAt` | string or null | When the last top-up was paid. |
| `spendAlerts` | object | `enabled`, the `monthlyBudgetUsd`, the `percents` of it that send an email, what auto top-up charged this calendar month (UTC) as `spentThisMonthUsd`, and when that starts over (`resetsAt`). |
| `checkoutEnabled` | boolean | Card payments are set up on this server. |

## PUT /v1/billing/auto-topup

`PUT https://api.primaryapi.com/v1/billing/auto-topup`

Auth: Dashboard session only (owner, admin or billing member)

Changes any of the settings and answers the new state. Body (every field optional):

```json title="Request"
{
  "enabled": true,
  "thresholdCredits": 2500,
  "amountCredits": 25000,
  "spendAlerts": { "enabled": true, "monthlyBudgetUsd": 100, "percents": [50, 80, 100] }
}
```

`thresholdCredits` is 100 to 1,000,000 in steps of 100; `amountCredits` is an amount that can be bought (1,000 to 1,000,000 in steps of 100); `percents` are 10, 20 … 100, each at most once; the budget is $1 to $100,000. Turning auto top-up on needs a saved card: without one the answer is `422 unprocessable`. If the balance is already below the threshold, the first top-up starts at once.

## POST /v1/billing/card/setup

`POST https://api.primaryapi.com/v1/billing/card/setup`

Auth: Dashboard session only (owner, admin or billing member)

Opens Stripe's page to save a card for auto top-up; nothing is charged. Body: `{ "enableAutoTopup": true, "thresholdCredits": 1000, "amountCredits": 10000 }` (all optional; with `enableAutoTopup`, auto top-up turns on with those settings as soon as the card is saved). **200 OK**: `{ "url": "https://checkout.stripe.com/…" }`. Stripe sends the browser back to Billing.

## DELETE /v1/billing/card

`DELETE https://api.primaryapi.com/v1/billing/card`

Auth: Dashboard session only (owner, admin or billing member)

Forgets the saved card and turns auto top-up off; answers the new state. The card stays in your billing details with Stripe (a plan may still use it), where you can remove it too.

## GET /v1/workspace

`GET https://api.primaryapi.com/v1/workspace`

Auth: API key with view or full access, or a dashboard session

The workspace the credential belongs to.

| Field | Type | Description |
|---|---|---|
| `id` | string | Workspace id. |
| `name` | string | Workspace name. |
| `type` | string | `personal` or `team`. |
| `balanceCredits` | integer | Spendable credits: bought, welcome and included. |
| `promoCredits` | integer | Welcome credits included in the balance. |
| `restrictedAccess` | boolean | Whether the workspace may call [restricted APIs](/docs/restricted-apis). |
