Windpaint
Account

Billing

Read your credit balance, statement, holds, usage and rate limits; set the low-balance warning and asset retention; and buy credits through Stripe Checkout.

Billing endpoints cover your organization’s prepaid credits. How credits, holds and expiry work is explained in Billing.

All billing endpoints return {"data": ...}. The storage settings endpoints live under /v1/account but are documented here because they set what you pay for storage. Credit amounts are decimal strings with two places, such as "612.40".


GET /v1/billing/balance

Your current balance, broken down by source and by lot.

Permission: billing:read

organization_idstring

Your organization’s id.

availablestring

Credits you can spend now. Already excludes held.

heldstring

Credits reserved by jobs still running.

by_sourceobject[]

Spendable credits totaled per source.

next_expirystring | null

When the soonest-expiring lot expires, or null if nothing expires.

next_expiry_amountstring | null

Credits left in that lot.

lotsobject[]

Every unexpired lot with credits left, in spend order.


GET /v1/billing/ledger

Your statement: every movement of credits, newest first.

Permission: billing:read

project_idstring

Only entries for this project (UUID). Grants and expiries have no project, so they’re excluded when you filter.

sincestring

ISO 8601 timestamp. Entries at or after this time.

untilstring

ISO 8601 timestamp. Entries before this time.

limitintegerdefault:100

Page size, 1 to 500.

offsetintegerdefault:0

Entries to skip.

dataobject[]

The page of entries.

totalinteger

Entries matching your filters across all pages. Sits next to data.


GET /v1/billing/holds

Credit holds placed by generation jobs, newest first. Each job has one hold.

Permission: billing:read

statusstring

held (job still running), captured (job completed and was charged) or released (job failed, was flagged or canceled). Omit for all.

limitintegerdefault:100

1 to 500.

dataobject[]

GET /v1/billing/usage

Credits charged and jobs completed, per project per day (UTC), newest day first. Only completed jobs count. Not paginated.

Permission: billing:read

sincestring

ISO 8601 timestamp. Only jobs that finished at or after this time. Omit for all time.

dataobject[]

GET /v1/billing/limits

Your organization’s rate limit tier, its limits, and what you’ve used in the current minute.

Permission: billing:read

organization_idstring

Your organization’s id.

tierinteger

1 to 4. Set by lifetime credit purchases; see tiers.

tier_sourcestring

purchases, or override when Windpaint has set custom limits for your organization.

lifetime_purchases_centsinteger

Total paid top-ups, in US cents.

limitsobject
usageobject
next_tierobject | null

The next tier: tier, min_purchases_cents (lifetime purchases needed) and its limits. null at tier 4 or when your limits are overridden.

overridesobject

Custom values Windpaint has set: tier, concurrent_jobs and submits_per_minute, each null when not overridden.

This call counts toward your requests per minute.


GET /v1/billing/settings

Read the low-balance warning threshold.

Permission: billing:read

low_balance_thresholdstring | null

Warn when available drops below this. null means the warning is off.

low_balance_notified_atstring | null

When the current warning fired. null means it’s armed (your balance is at or above the threshold, or no warning has fired yet).


PUT /v1/billing/settings

Set or clear the low-balance threshold. When available falls below it, Windpaint emails the organization and fires the billing.credits_low webhook event once. Saving re-arms the warning and checks your current balance right away, so a threshold above your balance fires immediately.

Permission: billing:write

low_balance_thresholdnumber | string | nullrequired

Credits, zero or more. null turns the warning off.

Returns the settings after the change, in the same shape as GET /v1/billing/settings.

Errors: 422 for a negative threshold.


Storage settings

How long your organization keeps assets, the storage price, and how much you store. See Asset retention for how expiry and storage billing work.

GET /v1/account/storage

Permission: orgs:read

Returns {"data": {"storage": Storage}}.

asset_retention_daysinteger | null

Days new assets are kept before they’re deleted, from 1 to 365. null keeps them until you delete them. Defaults to 7.

free_retention_daysinteger

Days of storage included with every asset: 7. Storage past this is billed.

max_retention_daysinteger

The largest value you can set: 365.

credits_per_gb_monthstring

The price of storage past the free days, in credits per GiB per 30 days, as a decimal string.

stored_bytesinteger

Bytes your organization stores now.

billable_bytesinteger

The part of stored_bytes that’s past its free days and being billed.

PATCH /v1/account/storage

Change how long new assets are kept. Assets that already exist keep their expires_at.

Permission: orgs:update

asset_retention_daysinteger | nullrequired

1 to 365, or null to keep assets until you delete them. Anything over 7 days is billed past day 7.

Returns the settings after the change, in the same shape as GET /v1/account/storage. A value outside 1 to 365 returns 422 with asset_retention_days must be between 1 and 365 days.


GET /v1/billing/topups/quote

Current top-up price and limits. Read these instead of hardcoding them.

Permission: billing:read

usd_per_creditstring

Price of one credit in US dollars.

min_creditsinteger

Smallest top-up.

max_creditsinteger

Largest single top-up.

expiry_daysinteger

Days bought credits stay usable after payment.

currencystring

Always usd.


GET /v1/billing/topups

Your top-ups, newest first, including pending and expired checkouts.

Permission: billing:read

limitintegerdefault:50

1 to 200.

dataobject[]

POST /v1/billing/topups

Start a Stripe Checkout session to buy credits. Send the user to checkout_url. Credits are added when Stripe confirms payment; poll GET /v1/billing/topups or the balance to see it land.

Permission: billing:write

creditsintegerrequired

Credits to buy, between min_credits and max_credits from the quote (100 to 100,000 today).

success_urlstring

Where Stripe sends the user after paying. Defaults to the dashboard’s Billing page.

cancel_urlstring

Where Stripe sends the user if they cancel. Defaults to the dashboard’s Billing page.

Returns 201:

topupobject

The new top-up, status: "pending". Same fields as in GET /v1/billing/topups.

checkout_urlstring

Stripe-hosted payment page.

Errors: 422 for an amount outside the limits, 503 if the payment provider can’t start checkout (the top-up is recorded as expired; nothing is charged).