Skip to main content
A plan is the template you create subscriptions from. Its prices charge for the metered features you defined and for fixed fees, and a new subscription copies the plan’s matching prices into its own line items. A price set up wrong bills nothing, blocks subscription creation, or leaves existing subscribers on an old rate.
Create a plan with Create plan, then add prices with Create price or Create prices in bulk, with entity_type set to PLAN and entity_id set to the plan’s ID. Add entitlements with Create entitlement. For step-by-step setup, see Creating a plan and Updating a Plan Price.

​
Packaging prices, entitlements, and credit grants in a plan

A plan holds three kinds of records: Because a subscription copies prices when you create it, changing a plan’s price doesn’t change what existing subscribers pay. See Changing a price on a plan with live subscriptions. An addon holds the same three records, but a subscription has exactly one plan. You attach addons when you create the subscription or later with Add addon to subscription. The attach fails unless one of the addon’s prices has the subscription’s currency and a billing period that equals or divides evenly into the subscription’s, or is ONETIME.

​
Choosing the type, billing model, and cadence of a price

This Create price body adds a usage charge to a plan, billed in graduated tiers at the end of each month:
  • type USAGE charges for a metered feature: set meter_id to the feature’s meter_id. FIXED charges a recurring or one-time fee, such as a platform fee or a per-seat fee, priced for the line item’s quantity. That quantity starts at 1, or at min_quantity when you set one.
  • billing_model FLAT_FEE charges amount per unit. PACKAGE charges amount for each block of transform_quantity.divide_by units. TIERED charges by tiers and tier_mode.
  • currency, billing_period, and billing_period_count Decide which subscriptions get the price. billing_period is DAILY, WEEKLY, MONTHLY, QUARTERLY, HALF_YEARLY, ANNUAL, or ONETIME. billing_period_count has no default, so send 1 unless the price covers several periods.
  • invoice_cadence ADVANCE bills a fixed charge at the start of the period it covers, and ARREAR bills it at the end. Usage is always billed in arrear.
  • price_unit_type FIAT by default. CUSTOM, with a price_unit_config, prices in your own pricing unit, such as credits. Flexprice converts the amount into currency at the unit’s conversion_rate when it creates the price.

​
Price combinations that Flexprice rejects

Creating a price with any of these fails with 400 and the message shown: The first two rules together mean that a ONETIME price is always FIXED.

​
Pricing usage with volume and slab tiers

Each tier’s up_to is inclusive: with up_to: 1000, the 1,000th unit is in that tier. tier_mode decides how the tiers combine. For the tiers above and 3,000 units in a period: Charges from 0 to 6,000 units: SLAB rises steadily to 470 dollars, while VOLUME drops from 100.00 to 80.08 dollars at 1,001 units and from 400.00 to 250.05 dollars at 5,001 units, ending at 300 dollars Charges from 0 to 6,000 units: SLAB rises steadily to 470 dollars, while VOLUME drops from 100.00 to 80.08 dollars at 1,001 units and from 400.00 to 250.05 dollars at 5,001 units, ending at 300 dollars
  • Leave up_to null on the last tier. With SLAB, units above the highest up_to aren’t charged. With VOLUME, they’re charged at the last tier’s rate.
  • Check the VOLUME boundaries. Crossing a boundary reprices every unit, so 1,000 units cost $100.00 and 1,001 units cost $80.08. Use SLAB when the bill should never drop as usage grows.
  • Use flat_amount for a fixed fee per tier. It’s added once for the tier the total falls in with VOLUME, and once for each tier that usage reaches with SLAB.
Set tier_mode on every TIERED price. Flexprice accepts a TIERED price without one, and that price calculates every charge as 0.

​
Rounding usage into packages

A PACKAGE price charges amount for each block of transform_quantity.divide_by units. transform_quantity.round handles the last, partial block: up, the default, bills it as a full block, and down drops it. With "amount": "10" and "divide_by": 1000: With round: down, a customer who stays below one block pays nothing for the price.

​
Matching plan prices to each subscription by currency and billing period

One plan can hold prices in several currencies and billing periods. When you create a subscription with a currency and a billing_period, Flexprice attaches each plan price that hasn’t ended and that:
  • has the same currency, ignoring case, and
  • has the same billing_period, or is ONETIME.
A USD monthly subscription attaches the plan's USD monthly and one-time prices and skips the annual price and the EUR price A USD monthly subscription attaches the plan's USD monthly and one-time prices and skips the annual price and the EUR price When no price matches, creating the subscription fails with 400 and the message “No prices match the subscription criteria”. When the plan has no price with that billing period and no ONETIME price, the message is “The entity must have at least one price to create a subscription”. Add a price for every currency and billing period you sell before you offer them.
Flexprice compares billing_period, not billing_period_count. A plan with a MONTHLY price and a MONTHLY price with billing_period_count: 3 attaches both to every monthly subscription. Use QUARTERLY for a three-month price, or pass include_price_ids on the subscription to attach only the prices you list.

​
Combining entitlements and prices on a metered feature

An entitlement controls what a customer can use, and a price controls what they pay. Subscription charges come from line items, and every line item comes from a price, so an entitlement alone never charges anything. For a metered feature: With usage_limit: 1000 and 1,500 units used in a billing period, the usage price bills 500 units, and its tiers apply to those 500. Set a usage_limit only for usage you include for free, and leave it out of a metered entitlement only when you don’t charge for that usage. Features covers what an entitlement sets for each feature type.

​
Changing a price on a plan with live subscriptions

Update price treats two kinds of fields differently:
  • Pricing fields: amount, billing_model, tier_mode, tiers, transform_quantity, bucket_size, price_unit_amount, and price_unit_tiers. Flexprice ends the price at effective_from, or now when you leave it out, and creates a new price with a new ID that starts at that moment. The response is the new price.
  • Other fields: display_name, description, lookup_key, metadata, and group_id. Flexprice edits the price in place.
The new price keeps the old one’s type, currency, billing period, invoice_cadence, and meter. effective_from needs a pricing field in the same request and can’t be earlier than the price’s start_date. Existing subscriptions keep billing the old price, because their line items still point to it. Subscriptions you create after effective_from get only the new price. A subscription created before a future effective_from gets line items for both prices, and the old one doesn’t end at effective_from. Unless you stop creating subscriptions on the plan until that date, update the price at the moment the change takes effect instead of scheduling it. To move existing subscribers to new usage prices, call Synchronize plan prices. It starts a background workflow over the plan’s active, trialing, draft, and incomplete subscriptions that haven’t been synced since its last usage price change, and for each one it:
  • adds a line item for each usage price the subscription is missing that matches its currency, billing period, and billing period count, unless you overrode that price on the subscription, and
  • ends each line item whose plan price has ended, at that price’s end date.
You can run the sync as soon as you schedule a change: the old line item then ends at effective_from, and the new one starts there. Get subscription (V2) returns plan_prices_out_of_sync: true until the sync reaches a subscription.
The sync adds usage prices only, but it ends the line item of any plan price that has ended, fixed prices included. After you change a fixed price, a subscription that the sync processes loses the old fixed charge and doesn’t get the new one. Move existing subscribers to a new fixed amount with Update subscription line item first: a line item updated that way points to a price of its own, which the sync leaves alone.

Plans

What a plan contains and how you manage plans in Flexprice.

Volume Tiered Pricing

How one unit rate applies to all usage, set by the tier the total reaches.

Advance vs Arrear

When a charge is billed relative to the period it covers.

Updating a Plan Price

Change a plan price and sync the change to existing subscriptions.