Balance and billing
Reference for GET /v1/balance, the credit ledger, credit orders and packs, Stripe checkout, and GET /v1/workspace.
Last updated
On this page
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.
GET /v1/balance
api.primaryapi.com/ v1/ balanceAuth: 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. |
curl -sS "https://api.primaryapi.com/v1/balance" -H "Authorization: Bearer $PRIMARYAPI_VIEW_KEY"{
"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
api.primaryapi.com/ v1/ billing/ ledgerAuth: 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
api.primaryapi.com/ v1/ billing/ ordersAuth: 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
api.primaryapi.com/ v1/ billing/ packsAuth: None
What can be bought, public:
{
"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
api.primaryapi.com/ v1/ billing/ checkoutAuth: 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
api.primaryapi.com/ v1/ billing/ auto-topupAuth: API key with view or full access, or a dashboard session
Auto top-up and spend alerts (how they work):
{
"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
api.primaryapi.com/ v1/ billing/ auto-topupAuth: Dashboard session only (owner, admin or billing member)
Changes any of the settings and answers the new state. Body (every field optional):
{
"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
api.primaryapi.com/ v1/ billing/ card/ setupAuth: 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
api.primaryapi.com/ v1/ billing/ cardAuth: 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
api.primaryapi.com/ v1/ workspaceAuth: 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. |