Credit Currencies | Paygent Documentation

Credit currencies are custom billing units you define once and reuse across wallets, agent pricing, plans, and orders. Instead of exposing raw USD per API call, you can sell “Credits”, “API Units”, or “Compute Hours” — each mapped to a USD conversion rate for invoicing.

Why credit currencies?

Challenge	How credit currencies help
Customers don’t think in fractional cents per token	Package usage as familiar “credits”
Prepaid packs and top-ups	Wallets hold balances in your currency
Postpaid “use now, pay later”	Accrue credits, convert to USD at invoice time
Platform fee bundles	Grant 10,000 credits/mo with a subscription

Create a credit currency

Sidebar → Credit Currencies → Create currency

Field	Description
Name	Human-readable label (e.g. “Paygent Credits”)
Code (key)	Unique identifier used in API, pricing, and wallets (e.g. `cx`, `Credits`) — cannot change after creation
Description	Optional internal notes
Default conversion rate	USD value of one credit (e.g. `0.01` → 100 credits = $1.00)
Type	`credit` (default) or `entitlement` — label only; same wallet behavior

The key is referenced everywhere: agent indicator pricing, platform fee credit benefits, wallet APIs, and orders. Pick a short, stable code and use it consistently in your SDK integration.

Where credit currencies are used

Credit Currencies (define once)
        │
        ├── Platform fee → Credit benefits (prepaid load)
        ├── Activity / Outcome indicator → CREDITS billing type
        ├── Customer wallet (prepaid or postpaid)
        └── Invoice line items (USD = credits × conversion_rate)

1. Platform fee credit benefits (prepaid)

On an agent or plan, under Platform fee → Credits / Entitlement:

Select the credit currency key
Set credits granted per billing period (e.g. 1,000/month)
Optional refresh frequency (Monthly, Quarterly, Annually)

Credits post to the customer’s prepaid wallet when the invoice is paid.

2. Indicator pricing (usage cost)

On Agents → Step 3: Pricing → Activity/Outcome indicator:

Set billing type to CREDITS
Select the same credit currency key
Set credits per indicator — cost per usage event (or per metered unit if a billable metric is linked)

3. Customer wallets

Each customer holds one active wallet per (customer, credit currency, organization):

Prepaid — credits loaded upfront; usage debits available_balance
Postpaid — usage accrues in postpaid_used; invoiced in USD at period end

Full wallet guide: Credits & Wallets

Conversion rate

The conversion rate translates credits to USD for invoices and reporting:

USD amount = credits × conversion_rate

Rate	Meaning
`0.01`	1 credit = $0.01 → 100 credits =$ 1.00
`0.002`	1 credit = $0.002 → 500 credits =$ 1.00

Credit currency default — suggested rate when creating wallets
Wallet override — each wallet can store its own conversion_rate (set at wallet creation)

Credit vs entitlement type

Both types behave identically at runtime. The type field is a label for dashboard display and balance API grouping:

Type	Typical use
`credit`	Consumable usage units
`entitlement`	Feature access or bundled allowances

Example: prepaid credit pack

Create currency cx with conversion rate 0.002
Agent platform fee: grant 10,000 cx/month
Indicator inference: CREDITS, 10 cx per call
Create order → wallet auto-created on first invoice
Customer pays invoice → 10,000 cx available
Each inference debits 10 cx until balance exhausted (or overage if enabled)

Example: postpaid credits

Create currency api_units with rate 0.01
Do not add platform fee credit benefits
Indicator api-call: CREDITS, 5 api_units per call
Manually create postpaid wallet for customer (dashboard)
Usage accrues → invoiced as USD at billing run

You cannot mix prepaid and postpaid for the same customer + currency. Create the wallet type you intend before the first invoice to avoid auto-creation of the wrong wallet type.

Checklist

✓ Credit currency created with stable key and conversion rate
✓ Agent/plan indicators use CREDITS billing with matching key
✓ Prepaid: platform fee credit benefits configured + order with wallet settings
✓ Postpaid: postpaid wallet created manually + indicator credits per signal set
✓ SDK sends usage events — wallet debits happen at billing time