Editing prices

How edits to a price, its entitlement template, and related fees propagate to existing subscribers

When you update a price, an attached entitlement template, or a linked fee, the change affects existing subscribers in one of four ways:

1. Propagated — the new value applies to existing subscribers from the next billing period onward.
2. Frozen — the current uninvoiced period keeps the old value; the new value applies starting next period.
3. Snapshotted — the value was captured at subscription activation and is not rewritten; the new value affects only new subscribers.
4. Blocked — the update is rejected when the price has active or pending-payment subscribers.

This page documents which fields fall into each category and the recommended workflow when you need to make a blocked change.

Propagation only applies to Standard Billing (billingVersion: 1). Legacy Billing uses a different flow — see Billing Versions.

Price-level fields

Editing a price (PATCH /v0/prices/{id}) rewrites the underlying record. At the next line-item sync, future-period line items are regenerated with the new values. The current uninvoiced period is frozen: existing line items keep their old unitPrice, displayName, and other captured values. A mid-cycle edit therefore does not retroactively change what the customer is billed.

Field	Edit allowed on price with active subs?	Effect on existing subs
properties.unitPrice (and other model-specific properties)	Yes	Frozen for current uninvoiced period; new value applies from next period
model	Only standard	Only standard is creatable or settable. dynamic, volume, and percentage are legacy: existing prices keep their model and keep billing, but you can’t create one or switch a price to one. Edit a legacy price’s other fields without resending model.
paymentTerm (in_advance ↔ in_arrears)	Yes	Current-period line items are replaced with the new direction (freeze is bypassed because the billing direction shifts)
invoiceDisplayName	Yes	Frozen for current uninvoiced period; new value applies from next period
billableMetricId	Yes	Future-period line items use the new metric; current uninvoiced items keep the old one
grantDiscountEnabled	Yes	Applies to future grant-discount calculations

Already-invoiced line items are never modified — invoices are immutable once issued.

Entitlement template propagation

When a price carries an entitlementTemplate, edits to the template fields propagate to existing subscribers’ grants through a separate path (grant reinitialization), with stricter rules than price-level fields.

Field	Edit allowed on price with active subs?	Propagates to existing subs?
issueAfterReset (any value, including 0 ↔ N and undefined ↔ N)	Yes	Yes — at next line-item sync
resetMaxRollover	Yes	Yes — at next line-item sync
resetMinRollover	Yes	Yes — at next line-item sync
expiration	Yes	Yes — at next line-item sync
preserveOverageAtReset	Yes	No — snapshotted at activation
issueAfterResetPriority	Yes	No — only rewritten as a side effect when another field above drifts
isSoftLimit	No — blocked	n/a — change rejected
usagePeriod presence (recurring ↔ one-time)	No — blocked	n/a — change rejected
usagePeriod.interval	No — blocked	n/a — change rejected
usagePeriod.anchor	No — blocked	n/a — change rejected

When propagation happens

Propagated template fields apply at the next line-item sync for each subscription, which typically aligns with the next period boundary. The change is not instant.

Internally, grant reinitialization runs as a post-sync hook after new metered line items are created. A drift detector compares the current template against the subscription’s active recurring grant. When a propagated field differs, the grant engine reinitializes the grant at the next period boundary.

If a subscriber is mid-period when you edit the template, the current period continues with the old grant values. The new values take effect from the next period.

Blocked template changes

updatePrice rejects the following template changes when the price has active or pending-payment subscribers:

• Toggling isSoftLimit
• Adding or removing usagePeriod (switching between recurring and one-time grants)
• Changing usagePeriod.interval
• Changing usagePeriod.anchor

These are blocked because mid-cycle propagation would surprise customers: cadence or anchor shifts would reissue grants at unexpected times, and flipping soft/hard limit would silently change overage behavior mid-period.

The API rejects the request with a 400 Bad Request describing the offending field. The diff is per feature, so edits to other (non-blocked) fields in the same call still go through.

Recommended workflow for blocked changes

1. Clone the price with the new shape (POST /v0/prices).
2. Reference the new price from a new plan, or update an existing plan’s price list to include it.
3. Migrate subscriptions off the old plan onto the new plan at the appropriate cycle boundary (terminate on the old plan, recreate on the new plan).

This pattern keeps existing subscribers on the old configuration until they migrate explicitly, avoiding mid-cycle surprises.

We are working on first-class plan transitions — upgrades, downgrades, and cross-grades — that will handle subscription migration automatically with proration and grant carry-over. The clone-and-migrate workflow above is the recommended path until those land.

Snapshotted template fields

Some template fields are captured on the entitlement at activation and never rewritten:

• preserveOverageAtReset — captured when the entitlement is provisioned. Editing it on the template affects new subscribers only.
• issueAfterResetPriority — does not itself trigger reinitialization. It is rewritten only as a side effect when another propagated field drifts.

If you need a snapshotted change to take effect on existing subscribers, follow the same clone-and-migrate workflow as for blocked changes.

Direct and purchase grants

Grants created via POST /v1/entitlements/{id}/grants (direct grants) or POST /v1/entitlements/{id}/grants/purchase (purchase grants) are independent of the entitlement template. Editing the template on a price never modifies these grants.

When a subscription is terminated, all metered-feature grants attached to it are voided — including direct and purchase grants. If you support prepaid credit packs, surface this in your cancellation flow so customers are not surprised by lost balances.

Next steps

• Prices — pricing models and payment terms
• Features and Entitlements — entitlement template reference
• Metered Entitlements — how metered grants are consumed
• Grants — direct and purchase grant APIs