Billing

PricklyMails bills from a token wallet, not per request. Every plan grants a monthly token allowance, and each verification check costs a fixed number of tokens, deducted as you use them.

The wallet model

A verification request reserves its estimated cost from your wallet at submit time. When the job finishes, the worker either commits the reservation (debiting exactly the checks that ran) or refunds it (for example when a check like SMTP is skipped against a provider that tarpits RCPT TO). You are only ever charged for checks that actually ran.

Plan and pricing config

GET /api/config is public and unauthenticated: it returns the plan grid (monthly token grant, prices, rate limit, max keys, max batch size), the top-up pricing, and the per-check token cost, so you can build pricing UI directly from the backend instead of hardcoding it.

curl https://api.pricklymails.com/api/config

Wallet balance

GET /api/wallet returns your current balance: available, reserved (held by in-flight jobs), total, and avg_daily_spend (a 30-day mean, useful to estimate remaining runway).

Transaction history

GET /api/wallet/transactions lists your ledger entries, newest first by default, paginated (limit default 20, cap 96; offset). Sort with sort (occurred_at, amount, or transaction_type) and order (desc or asc). Each entry carries job_uuid, the linked verification job, null for a credit or top-up.

GET /api/wallet/transactions/grouped returns the same ledger grouped by verification: one entry per job_uuid (a standalone credit or top-up is its own entry) carrying the latest lifecycle status, the net token effect, and the ordered reserve, commit, and cancel history. Same sort, order, and pagination as /api/wallet/transactions.

GET /api/wallet/balance-history returns a zero-filled, oldest-first series of your available balance, for charting. Accepts granularity (hour, day, week, or month) and days.

Subscription

GET /api/subscription returns your active plan, status, billing cycle, current period, and monthly credit grant. It returns a synthetic Free plan with HTTP 200 when you have never subscribed, so the endpoint never 404s.

Checkout and the billing portal

POST /api/billing/checkout creates a Stripe hosted checkout session for a plan subscription or a one-time token top-up, and returns the redirect URL. POST /api/billing/portal creates a session for the Stripe customer portal (manage payment methods, view invoices). Both return 503 Service Unavailable until Stripe billing is configured on the account.