Pricing models and the rating engine

This is the layer where usage finally turns into money, the rating engine takes a customer's usage, applies their plan's prices, and produces the line items on the invoice.

Example

A voice AI customer used 60,000 minutes in May. Your pricing has three tiers: the first 10k at $0.05 per minute, the next 40k at $0.04, and anything above 50k at $0.03. The rating engine walks the usage across the tiers and lands at (10k × $0.05) + (40k × $0.04) + (10k × $0.03) = $2,400 as a single line item on the invoice.

The four pricing models that matter 

• Pay as you go:

A flat rate per unit, like $0.01 per API call. The simplest model to explain to customers and the natural starting point for most usage-based products.

• Tiered pricing:

The more a customer uses, the cheaper each unit gets. The voice AI example above is a tiered plan: 60k minutes ends up at $2,400.

• Volume pricing:

Same setup as tiered, but the entire quantity gets priced at the rate of the highest tier reached. Say API calls cost $0.20 up to 2k, $0.10 from 2k to 4k, and $0.05 above 4k. A customer with 5,000 calls pays all 5,000 at $0.05 = $250. Crossing a tier drops the rate on everything.

• Hybrid pricing:

A fixed fee plus usage on top. $99 a month includes 50k emails. Every email beyond that costs $0.001. A customer sending 80k emails pays $99 + (30k × $0.001) = $129.

How Flexprice does this

Flexprice composes every shape above with a small set of enums. billing_model is FLAT_FEE, PACKAGE, or TIERED. tier_mode is VOLUME or SLAB.

{
  "billing_cadence": "RECURRING",
  "billing_period": "MONTHLY",
  "billing_model": "TIERED",
  "tier_mode": "SLAB",
  "type": "USAGE",
  "currency": "usd",
  "entity_type": "PLAN",
  "entity_id": "plan_growth",
  "meter_id": "meter_token_usage",
  "invoice_cadence": "ARREAR",
  "tiers": [
    { "up_to": 10000, "unit_amount": "0.002" },
    { "up_to": 50000, "unit_amount": "0.001" },
    { "up_to": null, "unit_amount": "0.0005" }
  ]
}

{
  "billing_cadence": "RECURRING",
  "billing_period": "MONTHLY",
  "billing_model": "TIERED",
  "tier_mode": "SLAB",
  "type": "USAGE",
  "currency": "usd",
  "entity_type": "PLAN",
  "entity_id": "plan_growth",
  "meter_id": "meter_token_usage",
  "invoice_cadence": "ARREAR",
  "tiers": [
    { "up_to": 10000, "unit_amount": "0.002" },
    { "up_to": 50000, "unit_amount": "0.001" },
    { "up_to": null, "unit_amount": "0.0005" }
  ]
}

{
  "billing_cadence": "RECURRING",
  "billing_period": "MONTHLY",
  "billing_model": "TIERED",
  "tier_mode": "SLAB",
  "type": "USAGE",
  "currency": "usd",
  "entity_type": "PLAN",
  "entity_id": "plan_growth",
  "meter_id": "meter_token_usage",
  "invoice_cadence": "ARREAR",
  "tiers": [
    { "up_to": 10000, "unit_amount": "0.002" },
    { "up_to": 50000, "unit_amount": "0.001" },
    { "up_to": null, "unit_amount": "0.0005" }
  ]
}

You can preview the resulting invoice at any time via POST /v1/invoices/preview without finalizing it.

2. Real-time entitlements

Billing tells you what someone owes at the end of the month, but entitlements tell you what they are allowed to do right now. Two systems, with two very different latency budgets.

Example

A customer on your Pro plan tries to make their 1,001st API call this month. The entitlement service has to decide in under 10 milliseconds: do you reject the call (hard limit) or let it through and charge overage (soft limit)? That same check runs on every single API call your product makes, all day, every day.

How entitlements show up

• Boolean:

Is feature X enabled for this customer? Like access to a premium model or a beta feature.

• Usage limit:

1,000 API calls per month, after which you either reject the request (hard limit) or allow overage (soft limit).

• Static value:

A config tied to the plan, like max seats or max projects.

How Flexprice handles entitlements 

Flexprice exposes entitlements at the customer level. You can check them in the hot path on every request because each entitlement carries a usage_limit, an is_soft_limit flag, and a reset period.

# Check what a customer is allowed to do right now
GET /v1/customers/:id/entitlements

or 

GET /v1/customers/{id}/entitlements

or 

GET /v1/customers/{customer_id}/entitlements 
postman request 'https://api.cloud.flexprice.io/v1/customers/string/entitlements' \
--header 'Accept: application/json' \
--header 'x-api-key: <your_api_key>' \
--body ''

# Check what a customer is allowed to do right now
GET /v1/customers/:id/entitlements

or 

GET /v1/customers/{id}/entitlements

or 

GET /v1/customers/{customer_id}/entitlements 
postman request 'https://api.cloud.flexprice.io/v1/customers/string/entitlements' \
--header 'Accept: application/json' \
--header 'x-api-key: <your_api_key>' \
--body ''

# Check what a customer is allowed to do right now
GET /v1/customers/:id/entitlements

or 

GET /v1/customers/{id}/entitlements

or 

GET /v1/customers/{customer_id}/entitlements 
postman request 'https://api.cloud.flexprice.io/v1/customers/string/entitlements' \
--header 'Accept: application/json' \
--header 'x-api-key: <your_api_key>' \
--body ''

The response returns every feature the customer is entitled to, their current usage, and whether they have hit a limit. For prepaid balances, Flexprice has a separate wallet system that handles real-time debit and FIFO credit consumption.

3. Invoice lifecycle

An invoice is not a static document; it usually moves through stages, and each transition matters. Get them wrong, and you end up with the "my invoice changed overnight" support tickets nobody wants.

Example

Imagine on May 31, around 11:59 PM, your customer's billing period closes. The system freezes the event window, recalculates the total from raw events, snapshots the prices used, and locks the invoice. But on June 2, a late event arrives with a timestamp from May 28. You will either issue a credit note for the difference or roll the late event into June's bill.

Here is what happens when you finalize a draft

• Stop accepting new events for that billing period.

• Recalculate the total one last time from raw events, not from cached rollups. This version becomes the source of truth.

• Save a snapshot of every price and meter used, so the invoice still makes sense even if you change pricing tomorrow.

• Late events after finalization get credit notes or roll to the next cycle. Never silent edits.

• Use a freeze window and stop accepting changes to a draft a few hours before it finalizes, so the customer's last view of the draft matches the final invoice.

How Flexprice does this

Flexprice gives you each step in the lifecycle as its own endpoint, plus a scheduled finalization that handles the freeze window automatically.

# Preview a draft total at any time
POST /v1/invoices/preview

# Finalize once the period closes
POST /v1/invoices/{invoice_id}/finalize

# Recalculate a draft after a late event
curl --request POST \
  --url https://us.api.flexprice.io/v1/invoices/{id}/recalculate-v2 \
  --header 'x-api-key: <api-key>'

# Issue a credit note instead of editing a finalized invoice
curl --request POST \
  --url https://us.api.flexprice.io/v1/creditnotes \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "invoice_id": "<string>",
  "reason": "DUPLICATE",
  "credit_note_number": "<string>",
  "idempotency_key": "<string>",
  "line_items": [
    {
      "amount": "<string>",
      "invoice_line_item_id": "<string>",
      "display_name": "<string>",
      "metadata": {}
    }
  ],
  "memo": "<string>",
  "metadata": {},
  "process_credit_note": true
}

# Schedule the draft to auto-finalize after a freeze window
curl --request POST \
  --url https://us.api.flexprice.io/v1/tasks/scheduled/schedule-draft-finalization \
  --header 'x-api-key: <api-key>'

# Preview a draft total at any time
POST /v1/invoices/preview

# Finalize once the period closes
POST /v1/invoices/{invoice_id}/finalize

# Recalculate a draft after a late event
curl --request POST \
  --url https://us.api.flexprice.io/v1/invoices/{id}/recalculate-v2 \
  --header 'x-api-key: <api-key>'

# Issue a credit note instead of editing a finalized invoice
curl --request POST \
  --url https://us.api.flexprice.io/v1/creditnotes \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "invoice_id": "<string>",
  "reason": "DUPLICATE",
  "credit_note_number": "<string>",
  "idempotency_key": "<string>",
  "line_items": [
    {
      "amount": "<string>",
      "invoice_line_item_id": "<string>",
      "display_name": "<string>",
      "metadata": {}
    }
  ],
  "memo": "<string>",
  "metadata": {},
  "process_credit_note": true
}

# Schedule the draft to auto-finalize after a freeze window
curl --request POST \
  --url https://us.api.flexprice.io/v1/tasks/scheduled/schedule-draft-finalization \
  --header 'x-api-key: <api-key>'

# Preview a draft total at any time
POST /v1/invoices/preview

# Finalize once the period closes
POST /v1/invoices/{invoice_id}/finalize

# Recalculate a draft after a late event
curl --request POST \
  --url https://us.api.flexprice.io/v1/invoices/{id}/recalculate-v2 \
  --header 'x-api-key: <api-key>'

# Issue a credit note instead of editing a finalized invoice
curl --request POST \
  --url https://us.api.flexprice.io/v1/creditnotes \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "invoice_id": "<string>",
  "reason": "DUPLICATE",
  "credit_note_number": "<string>",
  "idempotency_key": "<string>",
  "line_items": [
    {
      "amount": "<string>",
      "invoice_line_item_id": "<string>",
      "display_name": "<string>",
      "metadata": {}
    }
  ],
  "memo": "<string>",
  "metadata": {},
  "process_credit_note": true
}

# Schedule the draft to auto-finalize after a freeze window
curl --request POST \
  --url https://us.api.flexprice.io/v1/tasks/scheduled/schedule-draft-finalization \
  --header 'x-api-key: <api-key>'

Build vs buy

Honestly, this is the question that every team eventually runs into. Either you build it yourself, or pay someone else to handle it?

There is no universal answer to it; this usually comes down to where your engineering time is best spent and what your billing actually has to do.

Build

If billing is a crucial part of your product, your contract math is unusual enough that no vendor covers it, and you already have engineers on the team who have shipped billing systems before and know where the bodies are buried, you should go with building in-house.

Buy

If engineering bandwidth is your bottleneck, you want pricing experiments live in days instead of quarters, or you need audit trails, multi-currency, tax, and revenue recognition working on day one, buying is the smarter call here.

Hear it from one of our customers, Shubhendu Shishir, Head of Engineering at Simplismart.

Source

Simplismart scaled to 750+ pricing features on Flexprice without rewriting their billing infrastructure, and reclaimed roughly 30% of their daily engineering bandwidth that used to be stuck in billing work. That is the kind of leverage a good vendor gives you when the platform actually fits your model.

If you land on buy, Flexprice is an enterprise billing platform built for exactly this. The architecture you just read about is what powers it.

The bottom line on usage-based billing 

If you take one thing away from this, let it be that usage-based billing is not only one thing, but it is six layers stacked together, and the choices you make on each one will shape what your billing system will feel like a year from now.

The good news is that once you can see all six clearly, the rest of the calls get a lot easier. You know what your stack actually has to do. You know which decisions are reversible and which ones are not. And if you sit down with a vendor, you finally know which questions are worth asking.

Whatever path you pick, the goal is the same. A billing system that quietly does its job so you can get back to building your actual product.

If you want to poke around what this architecture looks like in code, Flexprice is open source. Fork it, run the APIs, break things, and see how it holds up.