Credits System

Overview

Cencori uses an organization-level prepaid wallet for AI usage.

• 1 credit = $1 USD.
• Credits are held at the organization level (not per project).
• Every successful AI request deducts usage from your org balance.
• If your org has no credits left, credit-gated tiers receive a blocked response until top-up.

Billing Model

Cencori billing has two layers:

1. Plan tier (Free / Pro / Team / Enterprise) for request limits and platform entitlements.
2. Credits wallet for usage-based AI charging.

Credits and plan tier work together. A paid org can still hit limits if:

• monthly request limit is reached,
• spend cap is reached, or
• credits are exhausted.

See Billing & Usage for plan and spend controls.

Top-Up Flow

When a user recharges:

1. They select a credit pack in Billing (Starter, Growth, Scale by default).
2. Checkout is created.
3. On successful payment, Cencori credits the organization wallet.
4. A topup transaction is written to the transaction history.

[!NOTE] Top-up settlement is idempotent: duplicate payment events do not double-credit the same order.

Usage Charging

For each successful request:

1. Cencori computes provider cost from model pricing and token/image/audio usage.
2. Cencori applies model/provider markup.
3. Final charge is logged.
4. Credits are deducted from org balance.
5. A usage transaction is written with a reference to the request log.

Formula:

provider_cost + markup = total_charge

Example

Request:

• Model: gpt-5.1
• Input tokens: 1,000
• Output tokens: 500

If the final calculated charge is 0.0245 credits, then:

• Your organization balance decreases by 0.0245.
• A usage record of -0.0245 is added to your transaction history.

Enforcement Behavior

Credits are enforced before request execution on credit-gated tiers.

• If balance is exhausted, API returns 403 with a credit exhaustion message.
• Recharge and retry to continue.

[!IMPORTANT] By default, Pro and Team tiers are credit-gated. Free and Enterprise can use separate policy paths based on deployment config.

Managed Keys vs BYOK

Credits do not force BYOK. You can run either mode:

See Bring Your Own Key (BYOK) for setup and tradeoffs.

Monitoring Credits

You can track credits in:

• Dashboard navbar: compact live credit pill.
• Billing page: current balance + recent credit transactions + recharge controls.
• Usage and Logs: request-level cost and token visibility.

Recommended Operator Checklist

If you operate your own Cencori deployment:

1. Configure Polar credit products (starter, growth, scale).
2. Set webhook endpoint and subscribe to order.paid.
3. Ensure provider keys are configured for managed mode.
4. Keep model pricing data current for accurate charging.
5. Set spend caps and monitor low-balance orgs.

Troubleshooting

Payment succeeded but credits not added

• Verify webhook endpoint is reachable and signed correctly.
• Confirm order.paid events are enabled.
• Check webhook logs for org resolution and metadata (purchase_type=credits_topup).

Credits not deducted on requests

• Check whether endpoint is routed through billing middleware/charged path.
• Confirm request reached a successful completion path.
• Verify request log contains charge greater than 0.

Credit balance exhausted errors

• Recharge org wallet.
• Confirm you are in the intended organization/project context.
• Verify tier gating policy for your environment.

FAQ

Are credits shared between organizations?

No. Each organization has an isolated wallet.

Can I use all models after top-up?

You can use models available in your Cencori catalog and configured provider access path (managed keys or BYOK).

Is auto-recharge available?

Not by default in current core flow. Top-up is explicit through billing checkout.