Skip to content

Pay-As-You-Go (PAYG) ​

PAYG allows customers to use resources and pay for what they actually consume, instead of buying credits upfront. Usage is tracked on a service balance, billed automatically at the end of each month, and collected via a stored payment mandate.

TiruPay supports two PAYG modes:

  • Direct PAYG - PAYG is activated on a customer's balance independently of any purchase. Customers can activate and switch plans themselves, as can services and admins.
  • Article-Bound PAYG - PAYG is tied to the purchase of a specific article or extension. It activates automatically on purchase and deactivates when the subscription ends.

Prerequisites

PAYG requires a balance type with payment_mode = PAYG. The customer's balance for that type is created automatically if it does not yet exist. A valid payment mandate must be linked to the balance for billing to work.

Compliance Requirements ​

Mandatory

The following requirements are not optional. They apply due to legal obligations and payment method requirements. Furthermore, they keep the amount of charge backs low and ensure a good user experience.

TOS

Accordingly to our Terms of Service, we will issue refunds of your orders for customers that can prove that they were not informed accordingly by your service on activation and ongoing costs of their Pay-as-you-go plan. In addition, we reserve the right to suspend services in such cases.

On activation ​

Use the TiruPay Customer Facing Frontend

If you use the TiruPay Customer Facing Frontend, you automatically comply with these requirements.

If the service implements activation of PAYG itself, the customer must be clearly informed, before activation, about all of the following:

Must discloseDetail
Limits and free amountsWhat free allowance and limit_payg apply to the plan
Cost per unitBoth net and gross pricing per unit
Billing frequencyHow often they will be charged
DeactivationThat PAYG can be deactivated at any time

Ongoing ​

The customer must be able to see:

  • their current balance
  • their balance usage history
  • a way to deactivate PAYG at any time

And for events that induce PAYG usage (e.g. pressing a button):

  • must be highlighted accordingly
  • must show the customer the (estimated) costs if possible

If the events are linked to automatic systems (e.g. an API call):

  • The automatic system must be disabled by default, and the activation of the automatic system must include all required details for a sound and transparent decision by the customer.

Use a limit ​

If possible, use a reasonable limit to ensure your customer can pay the amount that is charged. Start with a lower limit and increase it if necessary for the customer.

Core Concepts ​

PAYG Plan ​

A PAYG Plan defines the pricing structure for a balance type. Each plan belongs to exactly one balance type and can be activated on any balance of that type.

FieldDescription
nameDisplay name
descriptionOptional description
balance_type_idThe balance type this plan applies to
monthly_free_amountDefault free allowance per calendar month as a currency amount (optional). Mutually exclusive with monthly_free_units. Can be overridden per country via PaygPlanPrice.
monthly_free_unitsDefault free allowance per calendar month as a unit count (optional). Mutually exclusive with monthly_free_amount. Can be overridden per country via PaygPlanPrice or per category via PaygPlanPriceItem.
limit_paygDefault maximum billable overdraft (optional). Can be overridden per country via PaygPlanPrice.
unit_scaleScale factor: recorded units_used is divided by unit_scale before billing. For example, unit_scale = 1000 means 1,000,000 recorded tokens equal 1,000 billable units. Must be between 1 and 1,000,000. Can be updated directly only while no active activation exists for the plan; otherwise it must go through a PAYG plan condition change so existing customers are handled according to a policy.
is_activeWhether this plan is available for new activations. Inactive plans retain their configuration and can be reactivated.

A plan without an active flag is invisible to customers but fully visible to services and admins.

PAYG Plan Price ​

Each plan has one price container per country:

FieldDescription
country_codeThe country this price applies to
monthly_free_amountOverrides the plan-level monthly_free_amount for this country (optional). Mutually exclusive with monthly_free_units.
monthly_free_unitsOverrides the plan-level monthly_free_units for this country (optional). Mutually exclusive with monthly_free_amount. Must be NULL if any price item on this container has monthly_free_units set.
limit_paygOverrides the plan-level limit_payg for this country (optional).

Each price container holds one or more price items (one per usage category).

Payment Method Availability ​

Each PAYG plan price can specify which payment methods are allowed for that plan in that country. You explicitly add the payment methods that should be available - this works the same way as article payment method availability.

FieldTypeDescription
payg_plan_price_idstringThe PAYG plan price this belongs to
payment_method_idstringThe allowed payment method
is_enabledbooleanWhether this payment method is currently active (default: true)

No Payment Methods

If no payment methods are defined and enabled for a PAYG plan price, that plan cannot be activated by customers in that country.

Unique Combinations

Each payment method can only be added once per PAYG plan price. Adding the same payment method again reactivates the existing entry instead of failing.

Requires SUBSCRIPTION Configuration

PAYG billing charges the customer repeatedly over time, just like a subscription - even though it isn't tied to a TiruPay Subscription record. A payment method can only be linked to a PAYG plan price if the owning service has activated it via ServicePaymentMethodConfig with order_type = subscription. A payment method configured only for one_time orders is rejected here, since one-time-only methods (e.g. a single card charge without a stored mandate) cannot support recurring PAYG billing.

Managing these links requires an Admin account - a Service account cannot create, activate, deactivate, or delete them itself, unlike most other PAYG configuration.

PAYG Plan Price Item ​

Each price container has one price entry per usage category:

FieldDescription
usage_category_idThe usage category this price applies to
price_per_unitBilling rate per unit consumed beyond the free allowance
tax_category_idTax category to apply at billing time (required, must belong to the same country)
monthly_free_unitsFree units per month for this category only (optional). If set on any item, the parent PaygPlanPrice must have both monthly_free_amount and monthly_free_units as NULL.

A plan must have a price item for every usage category that will be recorded against it in the customer's country. A customer whose country has no matching price item cannot activate the plan. Prices can be scheduled for change - see PAYG Price Changes.

Free Allowances ​

Free allowances can be configured either by currency amount (monthly_free_amount) or by unit count (monthly_free_units), but not both - they are mutually exclusive at every level.

Three scopes exist, applied with the following precedence (most specific wins):

  1. Per-category (PaygPlanPriceItem.monthly_free_units): free units applied only to that category. If any item has this set, the parent PaygPlanPrice must have no free fields.
  2. Per-country (PaygPlanPrice.monthly_free_amount / monthly_free_units): overrides the plan default for that country.
  3. Plan-level (PaygPlan.monthly_free_amount / monthly_free_units): the default applied to all countries without a country-level override.

Example: multi-country AI API plan

A service sells API access with two usage categories - input_tokens and output_tokens. They want to offer this in Germany and the US with different pricing and allowances.

PaygPlan - "AI API Pro"

  • unit_scale = 1000 - customers send raw token counts; billing divides by 1000
  • monthly_free_units = 100 - 100 billable units (= 100,000 raw tokens) free globally by default
  • limit_payg = 50.00 - currency-independent default overdraft cap; this number has no currency attached at the plan level, so it should always be overridden per country/currency to reflect the actual monetary limit in the customer's currency

PaygPlanPrice for Germany (the country_code field holds the UUID of the Germany Country record)

  • limit_payg = 50.00 (explicit override recommended even when matching the plan default - see note above)
  • monthly_free_units and monthly_free_amount both NULL - inherits monthly_free_units = 100 from plan
  • Two PaygPlanPriceItems (no per-category monthly_free_units):
    • input_tokens: price_per_unit = €0.001, tax_category_id = UUID of the German 19% VAT tax category
    • output_tokens: price_per_unit = €0.003, tax_category_id = UUID of the German 19% VAT tax category
  • Because neither item sets monthly_free_units, the plan-level allowance of 100 billable units applies as a shared pool across both categories - input and output tokens together draw from the same 100 units.

PaygPlanPrice for the US (the country_code field holds the UUID of the US Country record)

  • limit_payg = 100.00 - higher cap for US customers
  • monthly_free_units and monthly_free_amount both NULL - but per-category allowances on the items take precedence (see below)
  • Two PaygPlanPriceItems with per-category monthly_free_units:
    • input_tokens: price_per_unit = $0.001, tax_category_id = UUID of the US tax category, monthly_free_units = 200 - 200 billable units free for input only
    • output_tokens: price_per_unit = $0.003, tax_category_id = UUID of the US tax category, monthly_free_units = 50 - 50 billable units free for output only

Because the US price items have per-category monthly_free_units, the parent PaygPlanPrice for the US must not have monthly_free_units or monthly_free_amount set (and it doesn't). The plan-level monthly_free_units = 100 is also suppressed for US customers - it is not used as a fallback for categories that have no per-category allowance. Each category's allowance stands on its own.

When a German customer activates this plan, a PaygActivation is created with:

  • unit_scale = 1000, monthly_free_units = 100, limit_payg = 50.00, currency_code = EUR
  • One PaygActivationCategoryPrice for input_tokens: price_per_unit = €0.001, monthly_free_units = NULL
  • One PaygActivationCategoryPrice for output_tokens: price_per_unit = €0.003, monthly_free_units = NULL

A US customer gets monthly_free_units = NULL on the activation (plan default suppressed) with limit_payg = 100.00, currency_code = USD, and per-category monthly_free_units on their snapshot entries.

If the price_per_unit for German input tokens is later raised, the German customer's snapshot is unaffected until they respond to a consent request.

Whole-unit balance types

If the balance type has unit_allow_decimal = false, the free allowance is matched against the unrounded usage cost, and only the resulting billable amount is rounded up to a whole unit. This means a usage fully covered by the free allowance is always billed as exactly 0, never inflated by rounding gross_cost up first.

PAYG Activation ​

A PAYG Activation is the runtime record that links a customer's balance to a specific plan. It stores an immutable snapshot at the moment of activation.

Activation-level snapshot (one per activation):

FieldDescription
monthly_free_amountFree allowance (currency amount) at time of activation
monthly_free_unitsFree allowance (unit count) at time of activation
limit_paygOverdraft limit at time of activation
unit_scaleScale factor at time of activation
currency_codeCurrency at time of activation

Per-category price snapshot (PaygActivationCategoryPrice, one per category):

FieldDescription
usage_category_idThe usage category this snapshot entry applies to
price_per_unitRate for this category at time of activation
monthly_free_unitsPer-category free units at time of activation (if configured per item)

These snapshots only change when a price change is accepted by the customer. This ensures that customers are always billed at the rate they agreed to when they activated PAYG, even if the underlying plan's price changes later. Tax rates are not snapshotted - they are always looked up from the current plan price at billing time.

StatusDescription
ACTIVECurrently active, usage is billed against this activation
CANCELLEDEnded, either manually, by a new activation, or by a subscription lifecycle event

Usage Recording ​

PAYG balances use the same items[] API as prepaid balances. Each item specifies a usage_category_id and a units_used count. TiruPay looks up the price_per_unit for each category from the active activation snapshot and computes the cost:

plain
scaled_units = units_used / unit_scale   (per category)
item_cost    = scaled_units × price_per_unit
total_cost   = sum of all item_cost values

For example, with unit_scale = 1000 and price_per_unit = €0.03 for a given category: recording 10,000 units results in (10000 / 1000) × 0.03 = €0.30.

unit_scale

unit_scale divides recorded units_used before billing. If unit_scale = 1000, one billable unit equals 1,000 raw units. This maps customer-facing units (e.g. "1 credit") to internal tracking units (e.g. "1,000 tokens"). Record raw units directly in units_used.

The monthly free allowance (if configured) is applied to total_cost before the balance is debited.

limit_payg controls how far the balance can go negative. Before a direct usage is created, the gross cost is checked against limit_payg. If the cost would push the balance past the limit, the call returns (false, null) and no usage is recorded.

Meter with idempotency keys

PAYG usage is typically recorded from an automated pipeline calling TiruPay on every billable event, often at high volume - exactly where a network blip and a naive retry can double-bill a customer. Send an Idempotency-Key with each usage-recording or reservation call, generated from something stable on your side (e.g. your own request or job ID), so retries of the same event settle once.

Reservations ​

PAYG balances support a reservation mechanism for cases where the actual unit count is not known until an operation completes (e.g. an LLM call). Reserve a cost estimate upfront by passing items[] with estimated units_used, then complete the reservation with the actual items[]. TiruPay recalculates the cost from the activation snapshot and adjusts the balance accordingly.

Idempotency keys apply to reservations too

Reserve creates a new reservation on every call - a retry after a dropped response reserves the amount again, so protect it with an Idempotency-Key the same way as recording usage directly.

Complete is different: it requires the usage to still be RESERVED, so a plain retry after a genuine success already fails with an error on its own rather than settling twice. An idempotency key doesn't add a safety net there so much as remove a false failure - it turns that retry back into the original success response instead of an error, as long as the first call already finished (a retry that lands mid-flight still gets a 409).

The monthly free allowance is applied at reservation time. If the reservation is cancelled, the free allowance is restored. On completion, the free allowance is recalculated against the actual units_used - the difference between the reserved and actual cost is settled automatically.

The limit_payg check is applied before the reservation is created. On completion, no second check is performed - the service has already rendered the work. If the actual cost exceeds the estimate and pushes the balance past -limit_payg, the excess is ultimately absorbed at the service's expense.

When several reservations are open at once, an overrun on one of them is not refunded - it is parked against the headroom of the still-open reservations. Concretely: with limit_payg = 50 and two open reservations of 25 each, completing the first at an actual cost of 30 leaves the balance at -55 (not clamped yet), because the second reservation's 25 may still shrink on its own completion. Only once no other reservation is open is any residual overage clamped to exactly -limit_payg. The net effect is that one reservation's overrun reduces the spendable headroom of the others, rather than being silently written off while they are still in flight. Direct usage bookings and brand-new reservations never receive this extended headroom - reservations always take priority, so those calls are checked against the hard -limit_payg and rejected if they would exceed it.

Direct PAYG ​

Direct PAYG is for balance types that are not tied to any article. Customers, services, and admins can all activate, switch, and deactivate it.

Activation ​

Any active PAYG plan linked to the balance type can be activated directly, provided:

  • The plan has a price for the customer's country.
  • No article-bound activation is currently active on the balance. If one exists, the subscription must be cancelled first.

Activating a new direct plan while a different direct plan is already active automatically cancels the previous one and creates a new activation with the new plan's snapshot. The already used free allowance in the current month is carried over to the new activation, meaning the customer cannot "double dip" by activating a new plan to get a fresh free allowance.

Deactivation ​

Direct PAYG can be deactivated at any time by a service user, admin, or the customer. There is no minimum commitment period.

Plan Switching ​

Switching from one direct plan to another is unrestricted. Each activation snapshots its price independently, so past usage is always billed at the rate that was active when it was consumed. The new rate takes effect immediately on the new activation.

Article-Bound PAYG ​

Article-bound PAYG links a PAYG plan to the purchase of a specific article or article extension. When a customer buys that article, PAYG activates automatically. When the subscription ends, PAYG deactivates automatically.

This is ideal for usage-based billing with a monthly subscription, where you want to charge a fixed fee for the subscription itself and then bill usage on top of it via PAYG. This model can be combined with direct PAYG or different article-bound configurations on the same balance type, but not with multiple article-bound configurations on the same article. This way you can have different billing models for the same underlying resource.

Example

You have an API product you want to sell. To include as many customers as possible, you want to offer different tiers with different cost models:

  • Basic: A direct PAYG plan with a low free allowance and a low limit_payg, allowing customers to try the API with minimal risk.
  • Usage-Based: Another direct PAYG plan with a higher free allowance, high price per unit and no limit_payg, allowing customers to pay strictly for what they use without fear of hitting a hard limit.
  • Pro: An article with an APA that activates a PAYG plan with a high free allowance and a moderate price per unit giving customers a buffer while still charging for heavy usage.
  • Premium: A more expensive article with an APA that activates a PAYG plan with the same high free allowance and a lower price per unit, ideal for power users.

Article PAYG Activation (APA) ​

An Article PAYG Activation is a catalog-level configuration entry - not customer-specific - that binds an article or extension to a PAYG plan. All customers who purchase the article get PAYG activated via this binding.

FieldDescription
article_idThe article to bind (mutually exclusive with article_extension_id)
article_extension_idThe extension to bind
payg_plan_idThe PAYG plan to activate on purchase

Each article and each extension can only have one APA. Deleting or repointing an APA directly only affects new purchases - existing customers' active PAYG activations continue running with their original snapshots until the subscription ends. Use Scheduled Article Changes to roll out a plan rebind or removal to existing subscribers in a controlled way.

Lifecycle ​

PAYG activates and deactivates automatically in response to subscription and order events:

EventEffect
Order completed (with APA-bound article)PAYG activated on the customer's balance
Order placed in PENDING state (early activation configured)PAYG activated immediately, before payment is confirmed
Subscription terminatedPAYG deactivated
Subscription expiredPAYG deactivated
Subscription pausedPAYG deactivated
Subscription unpausedPAYG reactivated
Subscription cancelled (not yet effective)No change - PAYG continues until the effective cancellation date
Order refundedPAYG deactivated
Order revokedPAYG deactivated

Lazy balance creation

If a customer does not yet have a balance for the PAYG plan's balance type at the time of purchase, TiruPay creates one automatically.

Conflict Protection ​

The system prevents conflicting activations:

  • A single order cannot contain two articles that would activate PAYG on the same balance type. This is validated at order creation time.
  • A direct PAYG activation on a balance is automatically cancelled when an article-bound activation takes over.
  • An article-bound activation cannot be overridden by a direct activation. The request is rejected if you try. The subscription must be cancelled first.
  • An article-bound activation from one APA cannot override an article-bound activation from a different APA. The existing subscription must terminate before a new one can activate PAYG on the same balance.

PAYG Price Changes ​

PAYG plan prices participate in the Scheduled Price Changes system.

What changes ​

When a scheduled price change takes effect, the price_per_unit on the affected plan price item record is updated to the new value. All new PAYG activations from that point pay the new rate.

Existing activations are updated when a consent request is resolved:

  • Accepted - the price_per_unit snapshot on the active activation is overwritten with the new rate. The customer pays the new price immediately.
  • Rejected / cancelled - the activation is cancelled. For article-bound activations this means the subscription is terminated. For direct activations the activation is cancelled directly.
  • Auto-applied - same as accepted; the snapshot is updated automatically without customer interaction.

On unpause, TiruPay creates a new activation record but copies the snapshot values from the most recent cancelled activation - the customer continues at the same price they had before the pause. A re-purchase or fresh activation always reads the current plan price.

Consent and notifications for article-bound customers ​

Because article-bound PAYG activations cannot be freely cancelled by customers - they are tied to a subscription with a minimum term - a PAYG price change triggers the same consent and notification flow as an article price change for all affected customers:

  • Customers with an active article-bound PAYG activation for the changed plan are notified.
  • Depending on the group's policy, they can accept, reject, or are automatically migrated.
  • Their affected subscriptions appear in the consent record.

Customers with direct PAYG activations also receive a consent request. On rejection their direct activation is cancelled at the effective date of the price change - there is no subscription to terminate, so TiruPay cancels the activation record directly at that point.

Special termination rights ​

A service can attach a special termination right to a price change group that includes a PAYG price change. This gives affected customers the right to cancel their subscription within a defined time window.

This applies to customers whose subscription involves an article with an APA linked to the changed plan - even if the article's own price is unchanged. The right to terminate follows the PAYG price change, not just the article price.

PAYG Plan Condition Changes ​

Beyond price_per_unit, the remaining PAYG plan fields - unit_scale, monthly_free_amount, limit_payg, and monthly_free_units - also participate in the Scheduled Price Changes system, using the same groups, policies, and consent flow. A ScheduledPriceChange targets one of these fields by setting payg_change_field alongside the target:

payg_change_fieldValid target(s)Level
unit_scalepayg_plan_id onlyPlan-wide only - there is no per-country or per-category unit_scale
monthly_free_amountpayg_plan_id or payg_plan_price_idPlan-level default or country-level override
limit_paygpayg_plan_id or payg_plan_price_idPlan-level default or country-level override
monthly_free_unitspayg_plan_id, payg_plan_price_id, or payg_plan_price_item_idPlan-level default, country-level override, or per-category override

Set the new value as new_unit_scale (integer) for unit_scale, or new_price (the field is still called new_price regardless of which condition it represents) for the other three.

json
{
  "name": "AI API Pro - raise free allowance",
  "effective_date_new_customers": "2026-04-01T00:00:00Z",
  "policy": "AUTO_APPLY",
  "changes": [
    { "payg_plan_id": "plan_123", "payg_change_field": "monthly_free_units", "new_price": "200" }
  ]
}

What changes on the plan ​

When the change takes effect, the field is updated directly on the targeted PaygPlan or PaygPlanPrice (or PaygPlanPriceItem, for a per-category monthly_free_units override). All new PAYG activations from that point use the new value.

Existing activations are updated per the group's policy, exactly as for price changes - NO_IMPACT keeps the old value on active activations, AUTO_APPLY/accepted consents adopt the new value immediately, and rejected/non-responding consents under a cancel policy terminate the activation (or its subscription, for article-bound PAYG). Updating a condition value re-snapshots the activation the same way a price update does - it does not touch price_per_unit unless that's also part of the same group.

unit_scale requires no active activations for a direct update

Unlike the other three fields, unit_scale can only be changed directly via PATCH on the plan while no active activation exists for it. Once at least one activation is active, change it through a ScheduledPriceChange with payg_change_field = "unit_scale" instead, so existing customers are migrated according to a policy rather than silently ending up with inconsistent per-unit pricing.

Only one active change per field ​

A plan, price, or price item can have multiple active ScheduledPriceChange records at once, as long as each targets a different field. For example, an active price_per_unit change and an active monthly_free_units change on the same PaygPlanPriceItem can coexist - but two active changes to monthly_free_units on the same item cannot.

Billing ​

PAYG balances are billed automatically on the 1st of each month. The process runs per balance:

  1. All pending usage since the last billing cycle is collected. Each usage record already contains the billable amount after the monthly free allowance was deducted at recording time.
  2. If the total pending amount is below the minimum billing threshold, billing is skipped for this cycle. The usage remains pending and carries over to the next month.
  3. Otherwise, a billing order is created with one position per usage record.
  4. The balance is immediately reset to 0 so the customer can continue working without interruption.
  5. The billing order is collected via the stored payment mandate.

Each balance produces its own billing order - there is no cross-balance or cross-currency aggregation. The order currency is taken from the PAYG activation snapshot, ensuring it always matches the country-specific rate the customer was activated with.

No mandate linked

If no valid payment mandate is linked to a PAYG balance, the balance is frozen automatically. At the end of the billing cycle, a billing order and invoice are still created - but payment collection is skipped. The order remains in PENDING status and must be completed manually by an admin, or resolved via a payment processor webhook.

PAYG billing and payment overdue

If payg_payment_grace_days is configured on the balance type and the billing order is not paid within that many days, the balance is automatically frozen. It is unfrozen as soon as the order is paid.