How Billing Works

PortaAIM uses a powerful billing engine to handle metering, rating, invoicing, payments, and collections. This page explains the core billing model so you can design your pricing strategy effectively.

The Billing Cycle

Usage Event → Rating → Balance Update → Billing Run → Invoice → Payment → Follow-up

1. Usage Event: Your application sends a usage event (e.g., "Customer X used 1,500 tokens")
2. Rating: The billing engine looks up the customer's plan, finds the applicable rate, and calculates the charge
3. Balance Update: The charge is applied to the customer's balance in real time
4. Billing Run: At the end of each billing period, the billing engine processes all pending charges — applies subscription fees, calculates cross-service discounts, converts trials, and finalizes the period
5. Invoice: An invoice is generated summarizing all charges for the period
6. Payment: The customer pays the invoice
7. Follow-up: For unpaid invoices, the billing engine re-sends the invoice; you can suspend service access or terminate the account

Billing Models

Each customer is created on one of two billing models, and the choice is recorded on the customer as billing_model. It decides how the customer's spending is described, while the mechanic underneath is the same for both: a credit limit controls how much they're allowed to owe before paid service usage is restricted.

The model is set when you create the customer and cannot be changed afterwards: a customer on the wrong one has to be replaced. Omit it and the customer is postpaid.

Postpaid (Pay After Use)

• Create the customer with billing_model: "postpaid" (or omit it, since this is the default) and a positive credit_limit (e.g. $500)
• Usage and subscription fees accumulate during the billing period as charges against the credit limit
• An invoice is generated at the period end with all charges
• The customer pays the invoice by the due date — this can be wired to a payment processor in your own app
• When the balance approaches the credit limit, paid services are blocked. Subscription fees continue to accrue regardless.
• Best for: enterprise customers, invoiced billing, subscription-first products

Prepaid (Pay Before Use)

In a prepaid setup the customer pays for credit upfront in your own application, and PortaAIM enforces "no using what you haven't paid for":

1. Collect a payment from the end user during signup (e.g. $50) using your own payment processor
2. Create the customer in PortaAIM with billing_model: "prepaid" and initial_funds: 50, which loads the money you collected in the same request. They are created on a credit limit of 0, so their usage can accrue no debt, whatever credit_limit you send. An update cannot raise it: a credit limit sent for a prepaid customer is rejected with 422.
3. The balance is now -50: a negative balance means the customer is $50 ahead, and available_funds reports the $50 they can consume. Omit initial_funds and they are created at zero, which means blocked until you record a payment.
4. As usage happens, the balance climbs from -50 toward 0 and available funds fall. When the balance reaches 0, paid services are blocked.
5. To let the customer continue, top up again the same way, and usage resumes.

• Best for: usage-heavy APIs, developer-facing products, anywhere the customer must pay before they can consume

In both models the underlying mechanic is the same: only the recorded billing_model, the credit_limit value, and the timing of payment collection in your application differ.

Billing Periods

Each customer has a billing period that determines when the billing run executes and invoices are generated. Today every customer is billed on a Monthly (anniversary) cycle — the invoice is issued on the same day each month as the customer's signup date. Additional period types are on the roadmap.

Period Type	Invoice Generated	Status
Monthly (anniversary)	Same date each month as signup	Available
Monthly (calendar)	First of each month	Coming soon
Weekly	Every 7 days	Coming soon
Custom	Configurable interval	Coming soon

How Charges Are Calculated

When a usage event arrives, the billing engine:

1. Identifies the customer from the account ID

2. Looks up their plan (which product is assigned)

3. Finds the tariff (price list) for the relevant service type

4. Matches the item by the longest of your item codes that the charge code reaches. The billing engine reads a dashed code as whole segments, and only when it is written in capitals: an item GEMINI-3 is charged for GEMINI-3-FLASH and GEMINI-3-PRO, but not for GEMINI-35, which parts from it inside a segment, and not for gemini-3-flash, which is not read as segmented at all. This is useful when you want a single price entry covering several model versions while still recording the exact model used: the full code is stored in the usage record, so you can analyze which models your customers are consuming without a separate pricing entry for each one.

5. Applies the rate — price per unit × quantity

6. Checks for tiered pricing (coming soon) — when multi-tier volume pricing ships, the rate for subsequent usage will adjust automatically once the customer's cumulative usage crosses a tier threshold. See Tiered Pricing below for the planned model.

7. Checks for included quota — if the customer's plan includes a free usage quota for this service, the usage is deducted from the remaining quota instead of being charged. The transaction is still recorded (with a zero charge amount), preserving full usage visibility. Quotas can be defined in two ways:

   • Usage-based quota: A quantity of the service itself — e.g., 1,000,000 free AI tokens per month
   • Monetary quota (coming soon): A dollar amount the customer can spend on the service — e.g., $100/month of Voice AI Bot usage

   Once the quota is exhausted, subsequent usage is charged at the plan's standard rate.

Pricing Example

Suppose you have a plan with:

• Monthly subscription: $49/month
• AI Token service: $2.00 per 1M tokens
• Included quota: 100M free tokens per month
• Pricing tier: After 1B tokens, price drops to $1.00 per 1M

A customer who uses 500M tokens in a month would be charged:

• Subscription: $49.00
• First 100M tokens: Free (deducted from included quota)
• Next 400M tokens: 400 × $2.00 = $800.00
• Total: $849.00

The Billing Run

The billing run is the critical end-of-period process that finalizes all charges before an invoice is generated. It runs automatically when a customer's billing period ends.

What the Billing Run Does

The billing run executes these steps in order:

1. Trial Conversion: Checks if any trial customers have expired trials. If so, switches them from the trial plan to the paid plan, unlocks billing, and starts charging subscription fees.

2. Subscription Fees: Calculates and applies all recurring charges — monthly plan fees, annual subscriptions, etc. Proration is enabled by default and applied automatically for customers who joined or changed plans mid-period, the annual term included.

3. Cross-Service Discounts (coming soon): Evaluates discount rules that depend on the customer's total consumption across services during the period. Examples of the planned behavior:

   • "50% off the subscription fee if per-usage charges on Cloud Compute exceed $100"
   • "Waive the platform fee if total API spend is above $500/month"
   • Graduated discounts based on aggregate volume across multiple services

4. Tax Calculation: Computes applicable taxes on all charges for the period.

5. Period Statistics: Aggregates all usage records (CDRs), computes totals, and generates the final invoice record.

Billing Run Timeline

Billing period ends (e.g., March 31 23:59)
  → Trial conversions processed
  → Subscription fees charged
  → Cross-service discounts applied
  → Taxes calculated
  → Invoice generated (e.g., April 1)
  → Payment due (e.g., April 30, based on due date setting)

Subscription Charges

Subscription fees are recurring charges defined per-plan and automatically applied to all customers on that plan.

Fees are charged in advance. A customer pays for a billing period at the start of it, not at the end.

Part periods are prorated. A customer who joins mid-period is charged only for the days from their join date to the end of that period. The same applies when they leave.

A plan change mid-period produces two entries: a refund of the unused part of the old plan, and a charge for the rest of the period on the new one. The customer is never charged twice for the same day and never gets a free one. Neither entry lands on the day of the change: the old plan is charged through the end of that day, and both entries appear at the customer's next billing run, after midnight in their time zone.

The annual term prorates the current period the same way, and prepays the next eleven. One charge covers twelve billing periods. The current period is charged only for its remaining days.

Tiered Pricing (coming soon)

You will be able to define pricing tiers that automatically adjust the rate as a customer's usage grows within a billing period. The planned shape:

Tier	Volume Range	Price per 1M Tokens
1	0 – 100M	$3.00
2	100M – 1B	$2.00
3	1B+	$1.00

When shipped, the billing engine will track cumulative usage per billing period and switch to the lower rate the moment a customer crosses a tier threshold. Until then, plans use a single per-unit price (optionally combined with a free quota and flat overage rate).

Cross-Service Discounts (coming soon)

Unlike per-service tiers, cross-service discounts evaluate a customer's total spending or usage across multiple services during the billing period. These will be calculated during the billing run, after all usage charges are finalized.

Examples:

• "If total Cloud Compute usage exceeds $100, reduce the subscription fee by 50%"
• "If combined API calls across all services exceed 1M, apply a 20% credit"
• "Waive the base platform fee for customers spending over $500/month on any combination of services"

This enables sophisticated pricing strategies like commitment discounts, loyalty rewards, and spend-based tier upgrades.

Included Quotas (Free Usage Allowances)

A plan can include free usage quotas that let customers use a service at no charge up to a defined limit. Quotas come in two flavors:

Usage-Based Quotas

A quantity of service units included for free each period.

Examples:

• 1,000,000 AI tokens per month
• 500 Speech-to-Text minutes per month
• 10,000 API calls per month

Monetary Quotas (coming soon)

A dollar amount the customer can spend on a service each period. Planned examples:

• $100/month of Voice AI Bot usage — the customer can use any combination of voice models until they hit $100 in charges
• $50/month of Image Generation — covers usage across all image models

Today, quotas are defined as a quantity of service units rather than a dollar amount.

How Quotas Work

• Quotas are defined per-plan and automatically applied to all customers on that plan
• When a customer uses a service with an active quota, usage is deducted from the remaining quota. The transaction is still recorded (with a zero charge amount), so you retain full visibility into what was consumed.
• Once the quota is exhausted, subsequent usage is charged at the plan's standard per-unit rate
• Quotas reset at the start of every billing period

The Invoice

After the billing run completes, the billing engine generates an invoice containing:

• Usage charges: Itemized by service and destination
• Subscription fees: Monthly/annual plan charges
• Discounts: Any cross-service or tiered pricing discounts applied
• Tax: Applied based on your tax configuration
• Credits/adjustments: Any manual balance adjustments
• Total due: Amount the customer needs to pay

Invoices can be downloaded as PDF or read through the API. The billing engine emails them to the customer on its own.

Collection & Non-Payment

After an invoice is generated, you need to ensure payment is received and take action when it isn't.

Payment Collection

1. Invoice issued: The billing engine emails it to the customer. Download the PDF from the Invoices page if you want to send it yourself as well
2. Customer pays: The customer pays via bank transfer, credit card, or other method outside PortaAIM
3. Record payment: Once payment is received, record it in PortaAIM via the customer's balance adjustment or the API
4. Record a refund, if you give one back: Money returned to a customer moves outside PortaAIM too, and the same balance adjustment records it. A refund reverses payments the customer made, so it cannot exceed them — see the Payments guide

Tracking Overdue Invoices

The Invoices page shows invoice statuses at a glance. Statuses come from the billing engine one-to-one — see the full list in the Invoices guide. The most common ones:

Status	Meaning
Paid	Fully paid
Unpaid	Invoice issued, payment not yet received
Partially Paid	A portion of the amount has been paid
Overdue	The billing engine marked the invoice overdue — payment wasn't received by the due date
Voided	Manually cancelled; excluded from outstanding totals

Use the status filter on the Invoices page to quickly find overdue invoices that need follow-up.

Handling Non-Payment

If a customer doesn't pay, you can take action through PortaAIM:

1. Let the reminder go out: The billing engine re-sends the invoice at a set interval after the due date. To reach the customer sooner, download the PDF from the Invoices page and send it yourself
2. Suspend the customer: From the customer detail page, suspend their account to block service access. The customer still owes the outstanding amount, and the billing engine credits back one day's subscription fee for each day that the suspension lasts. You can reactivate them after payment is received.
3. Terminate the customer: If non-payment continues, terminate the account to permanently close it and stop all billing.

tip

Configure your payment terms in Settings → Invoicing. The Net Terms setting (net_terms_days, default 15 days) controls how long customers have to pay before an invoice becomes overdue. For more information, see Invoice Settings.