Skip to main content
This quickstart runs the credit path end to end: you’ll set up a catalog, put a customer on a plan that grants credits, spend some, and watch the balance and ledger update. Every step is a real API call — no card needed. When you’re ready to charge cards and issue invoices, see Billing.
You’ll need a secret key (upay_sk_…) from the dashboard and the base URL https://api.useunitpay.com/v1. See Authentication.
1

Set up your catalog

Your catalog needs a credit currency, a plan that grants credits, and a feature to spend them on. The fastest way is to let Asterix build it from your pricing page:
curl https://api.useunitpay.com/v1/onboarding \
  -H "x-api-key: $UNITPAY_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{ "url": "https://yourcompany.com/pricing" }'
Or build it by hand — a credit currency (POST /v1/credit-currencies) and a free plan with a monthly credit grant rule (POST /v1/plans). See Billing for the catalog API and Credits for grant rules.
For this walkthrough you need a free plan ($0) that grants credits each cycle and a feature (e.g. ai-generation) that costs credits — so nothing has to be charged to see credits move.
2

Create a customer

The customer’s id is your own user or org id — pass your own externalId if you like.
curl https://api.useunitpay.com/v1/customers \
  -H "x-api-key: $UNITPAY_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{ "name": "Acme", "email": "dev@acme.test" }'
Response
{ "id": "cus_123", "name": "Acme", "email": "dev@acme.test" }
3

Subscribe them to the plan

Put the customer on your free plan. Because it’s $0, the subscription is created with no charge and the plan’s credits are granted on activation.
curl https://api.useunitpay.com/v1/subscriptions \
  -H "x-api-key: $UNITPAY_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{ "customerId": "cus_123", "planId": "pln_free" }'
Response
{ "kind": "created_no_charge", "subscription": { "id": "sub_123", "status": "active" } }
Self-serve subscriptions default to salesMotion: "self_serve" and collectionMethod: "charge_automatically". On a paid plan the response is charged_inline (card charged, first invoice paid) or requires_form (collect a card in the browser first) — that’s the Billing flow.
4

Check the balance

Confirm the credits landed. check is a read — it never changes state.
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": 100, "creditBalance": 100 }
5

Track usage — spend credits

Report that the customer used the feature. UnitPay resolves the credit cost and deducts it. This is the write that moves credits.
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": 10 }] }'
Response
{ "accepted": 1, "rejected": 0, "results": [{ "status": "ok", "flow": "credit", "creditsDeducted": "10", "creditBalance": "90" }] }
6

See it in the ledger

The balance is derived from the ledger — an append-only record of every grant and deduction. Read it back:
curl "https://api.useunitpay.com/v1/credit-ledger?customerId=cus_123" \
  -H "x-api-key: $UNITPAY_SECRET_KEY"
You’ll see the plan grant (+100) and your usage deduction (−10), with the running balance at 90. The live per-wallet balance is at GET /v1/credit-accounts?customerId=cus_123.
Credits granted → consumed → recorded. That’s the whole credit path working end to end.

​
Next steps

Charge cards & invoices

Paid plans, the card-on-file flow, and invoices.

Credits in depth

Denominations, grant priority, wallets, and top-ups.

Build the UI

Render balances, gates, and checkout with the React hooks.

How it works

The model behind both billing paths.