This reference guide covers the technical implementation of pricing models in API calls. For conceptual information and business use cases, see our Pricing Models Guide .
Supported Pricing Model Types When creating prices via the API, you must specify the type parameter with one of these values:
Type Description Model Parameter unitSimple per-unit pricing unitPricingModelfixedFixed price regardless of usage fixedPricingModeltieredPricing tiers based on total usage tieredPricingModelgraduated_tieredDifferent rates for usage in each tier graduatedTieredPricingModelprepaid_tieredPre-purchased units with tier pricing prepaidTieredPricingModelprepaid_fixed_tieredPre-purchased fixed package in a tier prepaidFixedTieredPricingModeltiered_percentagePercentage rates based on tier tieredPercentagePricingModelgraduated_percentageGraduated percentage rates by tier graduatedPercentagePricingModelvolume_percentagePercentage of transaction volume volumePercentagePricingModel
Each pricing type requires its corresponding model parameter to be provided in your API request.
Request Examples Below are examples of how to structure API requests for various pricing models:
{ "productId" : "prod_0000000000000001" , "type" : "unit" , "billingInterval" : "monthly" , "unitPricingModel" : { "pricePerUnit" : "9.99" }, "trialPeriodDays" : 14 } { "productId" : "prod_0000000000000001" , "type" : "fixed" , "billingInterval" : "monthly" , "fixedPricingModel" : { "pricePerUnit" : "10.00" , "units" : 5 , "total" : "50.00" } } { "productId" : "prod_0000000000000001" , "type" : "tiered" , "billingInterval" : "monthly" , "tieredPricingModel" : { "tiers" : [ { "minUnits" : 0 , "maxUnits" : 1000 , "pricePerUnit" : "0.20" , "fixedFee" : "0.00" }, { "minUnits" : 1001 , "maxUnits" : 10000 , "pricePerUnit" : "0.15" , "fixedFee" : "0.00" }, { "minUnits" : 10001 , "maxUnits" : null , "pricePerUnit" : "0.10" , "fixedFee" : "0.00" } ] } } { "productId" : "prod_0000000000000001" , "type" : "graduated_tiered" , "billingInterval" : "monthly" , "graduatedTieredPricingModel" : { "tiers" : [ { "minUnits" : 0 , "maxUnits" : 1000 , "pricePerUnit" : "0.20" , "fixedFee" : "0.00" }, { "minUnits" : 1001 , "maxUnits" : 10000 , "pricePerUnit" : "0.15" , "fixedFee" : "0.00" }, { "minUnits" : 10001 , "maxUnits" : null , "pricePerUnit" : "0.10" , "fixedFee" : "0.00" } ] } } { "productId" : "prod_0000000000000001" , "type" : "volume_percentage" , "billingInterval" : "monthly" , "volumePercentagePricingModel" : { "pricePerUnit" : "0.00" , "percentage" : "2.9" , "fixedFee" : "0.30" } } { "productId" : "prod_0000000000000001" , "type" : "unit" , "billingInterval" : "monthly" , "unitPricingModel" : { "pricePerUnit" : "49.99" }, "discount" : { "discountType" : "percentage" , "amount" : "20.00" , "durationType" : "fixed" , "durationValue" : 3 , "durationUnit" : "months" } } { "productId" : "prod_0000000000000001" , "type" : "unit" , "billingInterval" : "monthly" , "unitPricingModel" : { "pricePerUnit" : "0.10" }, "maximumSpend" : { "amount" : "1000.00" , "period" : "month" } } Required and Optional Fields Each pricing model has its own required and optional fields. The table below summarizes the base fields required for all pricing models:
Field Type Required Description productIdstring Yes The product ID this price applies to typestring Yes The pricing model type (see table above) billingIntervalstring Yes Billing interval: monthly, quarterly, or yearly [Model Parameter] object Yes The specific model parameters (varies by type)
Common Configuration Options All pricing models support these additional configuration options:
Trial Periods Spending Thresholds "maximumSpend" : { "amount" : "1000.00" , "period" : "month" } Discounts "discount" : { "discountType" : "percentage" , "amount" : "20.00" , "durationType" : "fixed" , "durationValue" : 3 , "durationUnit" : "months" } Field Reference For a complete reference of all available fields for each pricing model type:
The unique identifier of the product this price is for. Must be a valid
product ID in the format prod_XXXXXXXXXXXXXXXXXXXX.
The type of pricing model to use. Possible values:
unit - Simple per-unit pricing
tiered - Pricing tiers based on usage volume (each tier has
its own rate)
fixed - Fixed price regardless of usage
graduated_tiered - Pricing where units in different volume
tiers are charged at the tier's rate
prepaid_tiered - Pre-purchase a specific number of units
with tier-based pricing
prepaid_fixed_tiered - Pre-purchase a fixed package in a
specific tier
tiered_percentage - Percentage-based pricing with tier
structure
graduated_percentage - Graduated percentage rates based on
volume tiers
volume_percentage - Percentage of transaction volume
pricing
Optional number of trial days before billing begins for this price
Optional minimum spending threshold for this price
Show SpendingThreshold Properties
The monetary amount for the threshold (must be greater than 0)
The period for the threshold (e.g., "month", "year")
Optional maximum spending threshold for this price
Show SpendingThreshold Properties
The monetary amount for the threshold (must be greater than 0)
The period for the threshold (e.g., "month", "year")
Optional discount to apply to this price
The type of discount. Possible values: percentage,
fixed
The amount of the discount - for percentage discounts, this is a
percentage (e.g., "10.00" for 10%)
How long the discount applies. Possible values:
monthly_rolling, fixed
The duration value, required if durationType is fixed
The unit of the duration. Required if durationType is fixed.
Possible values: days, weeks,
months, years
The billing interval for this price. Possible values:
monthly, quarterly, yearly
Required when type is unit
Show UnitPricingModel Properties
The price charged per unit
Required when type is fixed
Show FixedPricingModel Properties
The total fixed price (typically units × pricePerUnit)
Required when type is tiered
Show TieredPricingModel Properties
Array of pricing tiers
Show PricingTier Properties
The minimum number of units for this tier
The maximum number of units for this tier (null for unlimited upper
bound)
The price charged per unit in this tier
Any fixed fee charged for this tier
graduatedTieredPricingModel
Required when type is graduated_tiered
Show GraduatedTieredPricingModel Properties
Array of pricing tiers
Show PricingTier Properties
The minimum number of units for this tier
The maximum number of units for this tier (null for unlimited upper
bound)
The price charged per unit in this tier
Any fixed fee charged for this tier
prepaidTieredPricingModel
Required when type is prepaid_tiered
Show PrepaidTieredPricingModel Properties
Array of pricing tiers
Show PricingTier Properties
The minimum number of units for this tier
The maximum number of units for this tier (null for unlimited upper
bound)
The price charged per unit in this tier
Any fixed fee charged for this tier
The number of prepaid units
prepaidFixedTieredPricingModel
Required when type is prepaid_fixed_tiered
Show PrepaidFixedTieredPricingModel Properties
Array of pricing tiers
Show PricingTier Properties
The minimum number of units for this tier
The maximum number of units for this tier (null for unlimited upper
bound)
The price charged per unit in this tier
Any fixed fee charged for this tier
The number of prepaid units
tieredPercentagePricingModel
Required when type is tiered_percentage
Show TieredPercentagePricingModel Properties
Array of graduated tiers
Show GraduatedTier Properties
The minimum number of units for this tier
The maximum number of units for this tier (null for unlimited upper
bound)
The percentage rate to charge in this tier
Any fixed fee charged for this tier
graduatedPercentagePricingModel
Required when type is graduated_percentage
Show GraduatedPercentagePricingModel Properties
Array of graduated tiers
Show GraduatedTier Properties
The minimum number of units for this tier
The maximum number of units for this tier (null for unlimited upper
bound)
The percentage rate to charge in this tier
Any fixed fee charged for this tier
volumePercentagePricingModel
Required when type is volume_percentage
Show VolumePercentagePricingModel Properties
The percentage rate to charge
Optional fixed fee to charge
Whether to charge this price on the contract start date for one-off prices. If
false, the price will be charged on the first billing date. Only applicable
for one-off prices in the first subscription version.
Using with Subscription Versions When creating or updating subscription versions, you’ll include pricing model details in your request body. See the Create Subscription Version and Update Subscription Version endpoints for complete examples.
