Skip to main content
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.
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.

​
Volume (tiered ladder)

A volume price carries a ladder of bands instead of a single rate. The period’s total usage selects one band, and that band’s rate applies to every billed unit. A customer who lands in the third band pays the third band’s rate on all of their billed usage, not only on what they used above the second boundary. Set model to volume and put the ladder in properties.tiers. Each band carries upTo, its inclusive upper bound, and unitPrice. The previous band’s upTo is the exclusive lower bound, and the first band starts at zero. On the ladder above, 250 units select the middle band and bill 250 × $4.00 = $1,000.00. The last band carries upTo: null and takes everything above the highest bound. Bounds must ascend, and the API rejects a ladder whose bands are out of order rather than sorting them. When the price carries an entitlement allowance, total usage still selects the band, but only the usage above the allowance is billed. Give the same ladder a 100-unit allowance and 250 units still select the middle band — the customer is billed for 150 units at that band’s rate, 150 × $4.00 = $600.00. The allowance changes what you pay for, never which band you land in.
Because one rate applies to every unit, a volume total can fall as usage rises. On a ladder charging $5.00 up to 100 units and $3.00 above it, 100 units bill $500.00 and 101 units bill $303.00. The wider the gap between two adjacent rates, the bigger the drop at the boundary between them.
The API rejects a volume price combined with grant discounts (grantDiscountEnabled), a credit denomination (pricingUnitId), a combined invoice row (invoiceDisplayGroup), a proportional rate (rateType: "proportion"), or a fee. Each needs a single rate the ladder does not have — to refund an unused grant at, to draw a credit pool at, to contribute to the combined row, or to take a share of — and fees are always standard. Band rates cannot be negative either. To bill a usage-scaled rebate, use a standard price with a negative unit price.

​
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:
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. 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:
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

​
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
paymentTerm accepts in_advance and in_arrears.

​
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
  • A single price can carry at most one entitlement template
See Features and Entitlements 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