How UnitPay works

UnitPay is the billing engine where dollars and credits are both first-class. You model what you sell once — a catalog of products, plans, and (optionally) credit currencies — attach customers to it, and report usage. From there, everything comes down to two ideas: the path value takes when it moves out, and the two verbs your app calls at runtime.

The two paths

Usage flows down one of two paths. The difference is when money settles.

	Dollar billing	Credit billing
When you charge	At invoice time — usage adds up, you bill later	At usage time — credits come off a balance instantly
The result	An invoice, auto-charged to a card	A balance that goes down and refills or tops up
Feels like	A monthly bill	A prepaid wallet or an allowance
Classic for	API metering	AI products, packs, plan allowances

You don’t pick one for your whole business. You choose per plan, and a single plan can do both — a dollar price for the subscription and a credit grant that refills every cycle.

The two verbs

At runtime your app only ever does two things: it checks whether a customer is allowed to do something, and it tracks that they did it.

check — before the action

Ask UnitPay whether the customer has access before you do the work.

curl https://api.useunitpay.com/v1/check \
  -H "x-api-key: $UNITPAY_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{ "customerId": "cus_123", "featureSlug": "ai-generation", "requestedUsage": 1 }'

Response

{ "access": true, "remaining": 42, "creditBalance": 42, "feature": { "slug": "ai-generation", "type": "credit" } }

access is false when the customer is out of balance or the feature isn’t in their plan. In your UI, the React SDK does the same check synchronously — see React SDK.

track — after the action

Report what happened. UnitPay routes the event by how the plan is priced: it deducts credits, meters usage for a dollar invoice, or both.

curl https://api.useunitpay.com/v1/usage/track \
  -H "x-api-key: $UNITPAY_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{ "events": [{ "customerId": "cus_123", "eventName": "ai-generation", "quantity": 1 }] }'

Response

{ "accepted": 1, "rejected": 0, "results": [{ "status": "ok", "flow": "credit", "creditsDeducted": "1", "creditBalance": "41" }] }

check never changes state — it’s a read. track is the write that moves money or credits. Track from your server with a secret key so usage can’t be spoofed from the browser.

The objects you’ll use

Customer

Whoever you bill. Their id is your own user or org id — no extra id to store.

Plan

What a customer subscribes to: a price, entitlements, and credit grants.

Entitlement / feature

What a plan grants access to — what check reads.

Credit account & ledger

A customer’s wallet and the append-only record behind its balance.

Grant

One deposit of credits — from a plan, a drip, a promo, or a package.

Invoice

The dollar bill, auto-charged to a card at settlement.

Next steps

Quickstart

Set up a catalog, subscribe a customer, and watch credits burn — end to end.

Credits

The credit path in depth: grants, denominations, wallets, and top-ups.

Authentication

API keys, and the difference between sandbox and live.

Billing

Plans, subscriptions, payments, and invoices on the dollar side.

​The two paths

​The two verbs

​The objects you’ll use

Customer

Plan

Entitlement / feature

Credit account & ledger

Grant

Invoice

​Next steps

Quickstart

Credits

Authentication

Billing

The two paths

The two verbs

The objects you’ll use

Next steps