POST /v1/organizations/{organizationId}/billing/projects/{projectId}/preview
Previews a change on the selected project’s subscription in the supplied category: a fixed-charge quantity change, or a plan change with the held fixed charges it carries over. Prices the change by the billing engine exactly as making it would bill it now: dueNow is that invoice, with taxes and the payer’s credits applied. A quantity already paid for this period is not billed again, so a purchase after a release can be free. nextCharge is what is charged in advance at the next period start. For a fixed-charge change, pass quote on with the purchase so it is refused if the price or period no longer hold. This operation does not change billing. An upgrade bills the replaced plan’s usage to date and the new plan from now, less the replaced plan’s unused time; planChange says when it applies and which held fixed charges the target does not sell: released first for a change that applies now, released with a downgrade when it applies. additions quotes what is added once an upgrade applies, each billed when it is added, in planChange.additions and outside dueNow. Supply both organizationId and projectId; the organization must pay for the project.
- TypeScript
- Python
- Rust
TypeScript
Parameters
string
required
string
required
The project being billed.
Body
One of: BillingPreviewFixedChargeChangestring
required
Category slug, e.g. analytics or messaging.
FixedChargeChange
required
A quantity change made now, as a purchase or release makes it.
array of FixedChargeAddition
Fixed charges added once an upgrade applies, each billed when it is added rather than with the upgrade. Priced as if added now on the target plan and returned in planChange.additions, outside dueNow. Each must be sold by the target plan and named once.
string
required
Category slug, e.g. analytics or messaging.
string
required
Plan to change to, as a purchase of it changes it.
Returns
200 What the change would bill. PreviewProjectChangeResponse
integer | null
required
The payer’s credit balance once dueNow is charged: the credit the change issues included, less what dueNow uses. In dueNow’s currency. Null when the change charges nothing now (a downgrade).
BillingPreviewInvoice
required
Charged when the change is made, priced as the change bills it. No lines when it charges nothing now.
BillingNextCharge | null
required
What is charged in advance at the next period start for what is held after the change. Usage and a minimum commitment are billed after the period. Null when nothing is, or the subscription ends first.
BillingPlanChangeEffect | null
required
Set for a plan change, null otherwise.
FixedChargeQuote | null
required
Set for a fixed-charge change, null otherwise: the unit price, currency and period the preview was priced on. Pass them on with the purchase so it is refused if they no longer hold.
string
required
The IANA time zone the payer is billed in, e.g. America/Los_Angeles. Billing periods start and end at its midnights, so read their calendar dates in it.