Billing and invoices on top of credits: reconciling money with usage

A credits system tracks usage and entitlements: how many credits an account has and how they're consumed. Billing and invoices track money: what you charge, when, and how it matches that usage.

The gap between the two is where disputes, proration, refunds, and reconciliation live. If credits and money get out of sync, you face:

• Accounting problems
• Customer confusion
• Compliance risk

This article covers how to keep credits and billing aligned: mapping plans and usage to invoices, handling mid-cycle changes and refunds, and designing for reconciliation so finance and support have a single source of truth.

Credits vs. money

Credits are an internal unit of consumption (API calls, compute minutes, etc.). Money is what the customer pays.

The link: pricing

Your pricing connects the two:

• Credits per dollar exchange rate
• Plan price that includes an allowance
• Usage-based pricing per credit consumed

Simple case

For a simple model (one plan, one price, monthly), the mapping is straightforward:

• One invoice per period
• One charge
• Usage is "within allowance" or "overage at $X per unit"

Complex case

As soon as you have multiple plans, proration, refunds, or usage-based overage, the mapping gets complex. You need to say:

• "This invoice line is for plan X for period Y"
• "This usage (or credit consumption) belongs to that line"

The solution: clear references

This implies clear references between:

• Billing entities: subscription, invoice, line item
• Credits entities: account, plan, grant, consumption

Without that, reconciling "what did we charge?" with "what did they use?" becomes a manual spreadsheet exercise.

Invoicing and plan periods

For subscription plans, the usual pattern is: at the start of each billing period (or at renewal), you create an invoice (or send it to a payment provider) for the plan price.

Invoice structure

That invoice may include:

• Fixed amount: e.g., "Pro plan $99/month"
• Usage-based line items: e.g., "5,000 overage credits at $0.01 each"

Linking invoices to credits

The credits system has already granted the plan allowance for that period; the invoice is the monetary record of what you're charging for that period.

You need a way to tie "this invoice" to "this plan period for this account." For example, the invoice should have:

• account_id
• plan_id
• period_start
• period_end

Then when you need to answer "what did we charge for January?" or "what usage does this invoice cover?", you have a clear link.

Integration with billing providers

Many teams use a billing provider (Stripe, etc.) for the actual charge and store:

• The billing provider's subscription ID
• The billing provider's invoice ID

The credits system then references the same period (or the same subscription) so that usage and revenue can be reconciled.

Mid-cycle changes and proration

When a customer upgrades or downgrades mid-cycle, you have two layers:

1. Credits layer

When do they get the new allowance?

• Immediately?
• At period end?

2. Money layer

How much do you charge or credit?

Proration is the monetary side: you charge for the partial period on the new plan and possibly credit the unused portion of the old plan.

Credits and billing must agree

Whatever your policy, credits and billing must agree. If billing prorates and issues a new invoice but the credits system doesn't grant the new allowance until next month, the customer is charged for something they don't have yet.

One source of truth

The design should be: one source of truth for "what plan/period is active when," and both the credits engine and the billing engine consume that.

Mid-cycle changes then trigger coordinated updates:

• Plan change
• Proration logic
• Invoice (or Stripe update)
• Credits grant/revoke as needed

Refunds and chargebacks

When money comes back (refund or chargeback), you have to decide how that affects credits.

Common approaches

1. Claw back credits proportionally or in full for the refunded period
2. Leave credits as-is but mark the account or invoice as refunded (so you don't double-count revenue)
3. Revoke only unused credits for the refunded amount

Make it consistent and auditable

Whatever you choose, it must be consistent and auditable. Support and finance need to know:

• "We refunded $X for invoice Y"
• "We revoked Z credits"

That means the refund flow should update:

• Billing system: refund record
• Credits system: revoke or adjust

With a clear reference between them (e.g., refund_id or invoice_id on the revoke record).

Chargebacks are trickier

You may not have a clean "refund" event from your payment provider. You need a process to:

1. Record the chargeback
2. Apply the same credits policy (revoke or adjust)

This ensures usage and revenue stay aligned.

Reconciliation and reporting

Finance needs to reconcile: "total revenue this month" vs. "total usage (or credit consumption) this month" at some level of granularity (per plan, per segment). That's only possible if:

• Every charge (or invoice) can be tied to a plan and period.
• Every significant credit grant or consumption can be tied to the same (or to a clear "non-revenue" category like promo).
• Refunds and chargebacks are recorded and linked to the credits adjustments.

Then you can build reports: revenue by plan, usage by plan, overage revenue, refund impact. If credits and billing live in separate systems with no shared keys (account_id, period, plan_id), reconciliation is manual and error-prone. Design the links in from the start: shared identifiers and a clear policy for what gets invoiced and what gets granted or consumed when.

Summary and recommendations

Billing on top of credits requires:

• Explicit links between invoices (or charges) and plan periods and accounts, so usage and revenue can be reconciled
• Coordinated handling of mid-cycle changes so proration and credits grants/revokes stay in sync
• Clear policy and implementation for refunds and chargebacks so credits are clawed back or adjusted in a consistent, auditable way
• Reporting that can join credits data and billing data so finance has a single picture

Keep the coupling clean

If you're building the credits system and already use a billing provider:

• Credits system: source of truth for "what do they have access to?"
• Billing system: source of truth for "what did we charge?"
• Link them by: account, plan, and period

Integration is key

If you're considering a dedicated credits API, look for one that can integrate with your billing flow (e.g., webhooks or APIs that fire on plan change or renewal) so that credits and money stay aligned without custom glue code.

credits.dev gives you a solid credits and plans layer so you can focus on connecting it to your billing and invoicing workflow with clear, auditable links.