> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Configure pricing models and payment terms
Prices define how much you charge for each billable metric within a plan.
## Pricing models
### Standard pricing
Fixed cost per unit. Simple and predictable, and the model to reach for by default. Standard covers flat per-unit rates, percentage-style multipliers, and revenue share.
Every unit costs the same amount regardless of volume. If you charge \$0.001 per token, the 1st token costs the same as the 1,000,000th token.
**Use cases:**
* Flat rate per token
* Fixed cost per GB
* Standard hourly rates
* Per-seat licensing
* Percentage / revenue share (see below)
### Percentage and revenue share (standard multiplier)
To charge a percentage of a value, use a **standard** price whose unit price *is* the rate. The monetary value flows in as the metered quantity, so `quantity × unitPrice` produces the percentage charge — no separate "percentage" model needed.
**Example:** To take 10% of transaction value, create a standard price with `unitPrice: "0.1"`. A \$100 transaction bills \$10 (100 × 0.1). For a 2.9% processing fee, use `unitPrice: "0.029"`; for 1% revenue share, `unitPrice: "0.01"`.
**Use cases:**
* Revenue sharing
* Transaction / processing fees
* Commission models
* Marketplace takes
A standard multiplier is uncapped — there is no per-transaction minimum or maximum charge. If you need caps, apply them in your usage pipeline before sending the metered value.
### Usage-scaled rebates (negative unit price)
A **standard** price with a *negative* unit price is a rebate that scales with measured usage. It generates an ordinary metered line whose subtotal is negative, so it reduces the invoice rather than adding to it — and it recurs every billing period like any other price, inheriting plan versioning, per-subscription overrides, cadence and payment term.
**Example:** A price with `unitPrice: "-0.50"` against a usage metric rebates \$0.50 for every measured unit. At 300 units the line is `-$150.00`.
**Rebate threshold.** Attach a metered feature whose entitlement template sets `isSoftLimit: true`, and the rebate applies only to usage *above* the entitlement's allowance — "no rebate on the first N units". A soft-limit feature is required to combine a rebate with a feature.
A rebate can reduce a bill to \$0.00 but never below it. Configure rebate rates so the rebate stays below the charges it offsets over a billing period; if a rebate would exceed an invoice's charges, the invoice is held for review rather than issued. Lower the rebate rate — or raise the charges it offsets — and the held invoice can be recalculated and issued. A held invoice is never issued on stale totals: it either recalculates cleanly or stays held.
An `IN_SCOPE` rebate is folded into the charge lines **in the request sent to the tax provider**, so it is not filed as a separate line — the filing shows reduced effective unit prices that reconcile to the same total. Your customer's invoice is unaffected by that fold: the rebate keeps its own row there, with its own negative unit price. A rebate you declare `OUTSIDE_SCOPE` is not folded and is not sent to the provider at all, because it is not consideration for a supply. See [Supply scope](#supply-scope).
A negative unit price cannot be combined with grant discounts (`grantDiscountEnabled`), a hard-limit feature, or a credit-denominated price (`pricingUnitId`); the API rejects these.
**Feature basis.** Several prices may bill the same measured usage, each at its own rate — a rate plus a percentage, a rate plus a rebate, and so on. When a rebate price and a charge price share the same billable metric but attach to different features (one billing overage above an allowance, the other billing raw usage), they compute against different quantity bases. That is a valid configuration — a bundled allowance alongside a passthrough charge — but it is worth double-checking it is the one you intended.
### Legacy models *(read-only)*
`dynamic` and `percentage` are **legacy** models. Prices that already use them keep billing exactly as before, but new prices can no longer be created with them and existing prices can't be switched to them. Use `standard` instead — the API rejects these models on create/update, and the platform UI no longer offers them. The old `percentage` model's min/max caps have no `standard` equivalent (see the note above).
## Supply scope
A price declares whether its money is consideration for a supply — the one tax fact only you can state, because it is settled when you agree the deal, not derived from what was sold. It goes in a `tax` object:
```json theme={null}
"tax": { "supplyScope": "OUTSIDE_SCOPE", "outsideScopeLabel": "CASHBACK" }
```
The object is optional on create and update, and always present when you read a price back. On an update it is **replaced, not merged** — send it to change the declaration, omit it to leave the stored one alone. Putting a price back in scope therefore clears its label rather than leaving a stale one behind.
| Supply scope | What it does |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `IN_SCOPE` *(default)* | Consideration for a supply. It enters the taxable amount — positive as a charge, negative as a reduction in the price of the supply it applies to, which inherits the tax rate of the lines it reduces. |
| `OUTSIDE_SCOPE` | Not consideration for anything. It does not change the taxable amount, carries no tax, is not sent to the tax provider, and nets into the amount payable **after** tax. It still appears on the invoice — as its own charges row and as its own line in the tax summary. |
Every existing price is `IN_SCOPE`, and nothing about it changes. A usage-scaled rebate is a reduction in the price of what you supplied, so it belongs on the pre-tax side and the default gives that.
Declare `OUTSIDE_SCOPE` where the money is not a reduction in the price of anything you supplied. Card cashback is the usual case: it derives from card spend rather than from the subscription it appears beside, and often covers a different period.
`OUTSIDE_SCOPE` means "not consideration for a supply". It does **not** mean "a supply outside this jurisdiction" — exports and place-of-supply answers are worked out from the addresses on the sale by the tax provider, and are never declared on a price.
The choice changes the tax on the rest of the invoice, so it is a determination to make on the advice you hold, not a presentation setting. A \$1,000 supply at 20% with a \$100 rebate is \$180 of tax if the rebate is in scope and \$200 if it is outside it. Both are defensible positions on different facts; only one is right for yours.
Supply scope is **not** how a supply is classified. Standard, zero-rated, exempt and reverse charge all follow from what was sold, where the supply happens and who your customer is, and the tax provider determines them — so none of them is a value you set here.
### Out-of-scope label
`CASHBACK` is the only value, and it is **required** on an out-of-scope price. It names the amount in the invoice totals — `Cashback credit` where the figure is negative, `Cashback` where it is positive — so the wording follows the declaration rather than being retyped per price. It is rejected on an `IN_SCOPE` price, where nothing would read it.
A label is present exactly when the scope is `OUTSIDE_SCOPE`. Requiring it is what stops us printing wording nobody chose against your money; the trade is that you cannot yet record an out-of-scope position we have not named. If you have one, tell us and it becomes a label.
### The sign belongs to the label, not the scope
Out-of-scope money is not always a credit. A disbursement you paid to a third party as your customer's agent and recharge exactly, and a refundable security deposit, are both positive — and nothing about `OUTSIDE_SCOPE` says which way the money points. The invoice presents either direction correctly.
`CASHBACK` is the exception, because the word means money paid back: a `CASHBACK` price **cannot carry a positive `unitPrice`**, and must use the `standard` model. Exactly zero is fine — it bills nothing. When a label that points the other way is added, it will carry its own rule; this one is not a rule about being out of scope.
The sign check reads the amount the price will actually bill, so it is judged against your stored price as well as your patch. Adding `tax` to an existing price that charges is refused, and so is turning a stored cashback positive.
### On the invoice
An out-of-scope line keeps its own row in the charges table, with the quantity and rate that produced it, so the calculation stays self-evidencing. Its money nets in below the tax:
```
Subtotal (excl. VAT) US$1,159.75
VAT (20%) US$231.95
Total US$1,391.70
Cashback credit -US$168.69
Amount due US$1,223.01
```
The subtotal is the amount the tax was charged on, so `subtotal × rate` is the tax printed beside it. Each line also states its own tax clause under its billing window, and the tax summary lists the out-of-scope amount separately, with no rate and no tax amount against it.
## Payment terms
Control when and how customers are charged for usage.
### In advance
Charge at the start of each billing period before usage occurs. The customer is billed upfront for the upcoming period.
**Perfect for:**
* Recurring subscription fees
* Platform access charges
* Per-seat licensing
* Any fixed fee on Standard Billing plans
### In arrears
Accumulate charges throughout a billing period and bill at period end. Customers pay after usage has occurred.
**Perfect for:**
* Metered usage (tokens, API calls, storage)
* Enterprise contracts with NET payment terms
* Large transaction volumes
* Traditional invoicing workflows
### Instant *(withdrawn)*
`instant` charged in real time as each usage event occurred. It is no longer available. Use
`in_advance` or `in_arrears` instead.
`paymentTerm` accepts `in_advance` and `in_arrears`. No plan accepts `instant`, on either billing model. See [Billing Versions](/platform/billing/billing-versions) for payment term constraints by billing model.
## Linking a feature
A price can automatically provision an entitlement when a customer subscribes by linking it to an `entitlementTemplate`. This is how you grant access to features — quota limits, reset periods, and rollover behavior — directly through the plan's pricing.
To grant a feature without charging for it, set `unitPrice: "0"` on the price and attach the `entitlementTemplate`. When a customer subscribes to the plan, the entitlement is provisioned automatically.
Key points:
* The `entitlementTemplate` on the price defines the grant: quota amount, reset cadence, and rollover behavior
* Requires Standard Billing (`billingVersion: 1`)
* A single price can carry at most one entitlement template
See [Features and Entitlements](/platform/pricing/features) for the full configuration reference.
## Combining models
Mix different approaches within one plan to optimize for your business.
**Example: AI Platform**
* Base platform access: \$499/month (standard, in advance)
* Token usage: \$0.002/token (standard, in arrears)
* Enterprise support: \$5000/month (standard, in advance)
**Example: Data Warehouse**
* Storage: \$0.02/GB-month (standard, in arrears)
* Queries: \$0.75/query (standard, in arrears)
* Data export: 1% of monthly bill (standard multiplier, `unitPrice: "0.01"`, in arrears)
## Design principles
**Start simple.** Standard pricing covers 90% of use cases. Add complexity only when needed.
**Match customer expectations.** B2C favors charging in advance, B2B prefers invoicing in arrears.
## Next steps
* [Features and Entitlements](/platform/pricing/features) — Link features to prices for automatic entitlement provisioning
* [Meter Events](/platform/metering/meter-events) — Send usage data for Standard Billing metered prices
* [Billing Versions](/platform/billing/billing-versions) — Payment term constraints by billing model