Pricing Models API Reference

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
`unit`	Simple per-unit pricing	`unitPricingModel`
`fixed`	Fixed price regardless of usage	`fixedPricingModel`
`tiered`	Pricing tiers based on total usage	`tieredPricingModel`
`graduated_tiered`	Different rates for usage in each tier	`graduatedTieredPricingModel`
`prepaid_tiered`	Pre-purchased units with tier pricing	`prepaidTieredPricingModel`
`prepaid_fixed_tiered`	Pre-purchased fixed package in a tier	`prepaidFixedTieredPricingModel`
`tiered_percentage`	Percentage rates based on tier	`tieredPercentagePricingModel`
`graduated_percentage`	Graduated percentage rates by tier	`graduatedPercentagePricingModel`
`volume_percentage`	Percentage 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:

Request Examples

Unit Pricing Model

{
  "productId": "prod_0000000000000001",
  "type": "unit",
  "feeType": "metered",
  "billingDirection": "arrears",
  "billingInterval": "monthly",
  "unitPricingModel": {
    "pricePerUnit": "9.99"
  },
  "trialPeriodDays": 14
}

Fixed Pricing Model

{
  "productId": "prod_0000000000000001",
  "type": "fixed",
  "feeType": "fixed",
  "billingDirection": "advance",
  "billingInterval": "monthly",
  "fixedPricingModel": {
    "pricePerUnit": "10.00",
    "units": 5,
    "total": "50.00"
  }
}

Tiered Pricing Model

{
  "productId": "prod_0000000000000001",
  "type": "tiered",
  "feeType": "metered",
  "billingDirection": "arrears",
  "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"
      }
    ]
  }
}

Graduated Tiered Model

{
  "productId": "prod_0000000000000001",
  "type": "graduated_tiered",
  "feeType": "metered",
  "billingDirection": "arrears",
  "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"
      }
    ]
  }
}

Volume Percentage Model

{
  "productId": "prod_0000000000000001",
  "type": "volume_percentage",
  "feeType": "metered",
  "billingDirection": "arrears",
  "billingInterval": "monthly",
  "volumePercentagePricingModel": {
    "pricePerUnit": "0.00",
    "percentage": "2.9",
    "fixedFee": "0.30"
  }
}

With Discount

{
  "productId": "prod_0000000000000001",
  "type": "unit",
  "feeType": "metered",
  "billingDirection": "arrears",
  "billingInterval": "monthly",
  "unitPricingModel": {
    "pricePerUnit": "49.99"
  },
  "discount": {
    "discountType": "percentage",
    "amount": "20.00",
    "durationType": "fixed",
    "durationValue": 3,
    "durationUnit": "months"
  }
}

With Spending Threshold

{
  "productId": "prod_0000000000000001",
  "type": "unit",
  "feeType": "metered",
  "billingDirection": "arrears",
  "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
`productId`	string	Yes	The product ID this price applies to
`type`	string	Yes	The pricing model type (see table above)
`feeType`	string	No	Fee classification: `fixed` or `metered`. Defaults to the product’s fee type if omitted
`billingDirection`	string	No	When the charge is collected: `advance` (start of period) or `arrears` (end of period). Defaults to the product’s payment terms if omitted
`billingInterval`	string	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

"trialPeriodDays": 14

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:

productId

string

required

The unique identifier of the product this price is for. Must be a valid product ID in the format prod_XXXXXXXXXXXXXXXXXXXX.

type

string

required

The type of pricing model to use. Possible values:

Show Pricing Types

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

trialPeriodDays

integer

Optional number of trial days before billing begins for this price

minimumSpend

object

Optional minimum spending threshold for this price

Show SpendingThreshold Properties

amount

string

required

The monetary amount for the threshold (must be greater than 0)

period

string

required

The period for the threshold (e.g., "month", "year")

maximumSpend

object

Optional maximum spending threshold for this price

Show SpendingThreshold Properties

amount

string

required

The monetary amount for the threshold (must be greater than 0)

period

string

required

The period for the threshold (e.g., "month", "year")

discount

object

Optional discount to apply to this price

Show Discount Properties

discountType

string

required

The type of discount. Possible values: percentage, fixed

amount

string

required

The amount of the discount - for percentage discounts, this is a percentage (e.g., "10.00" for 10%)

durationType

string

required

How long the discount applies. Possible values: monthly_rolling, fixed

durationValue

integer

The duration value, required if durationType is fixed

durationUnit

string

The unit of the duration. Required if durationType is fixed. Possible values: days, weeks, months, years

feeType

string

The fee type classification for this price. Possible values: fixed (flat fee), metered (usage-based). If omitted, defaults to the product's fee type.

billingDirection

string

When the charge is collected relative to the billing period. Possible values: advance (charged at the start of the billing period), arrears (charged at the end of the billing period). This is the price-level equivalent of the product's paymentTerms field. If omitted, defaults to the product's payment terms.

billingInterval

string

required

The billing interval for this price. Possible values: monthly, quarterly, yearly

billingFrequency

string

The billing frequency for this price. Possible values: recurring, one-off. If omitted, defaults to the product's billing frequency.

unitPricingModel

object

Required when type is unit

Show UnitPricingModel Properties

pricePerUnit

string

required

The price charged per unit

fixedPricingModel

object

Required when type is fixed

Show FixedPricingModel Properties

pricePerUnit

string

required

The price per unit

units

integer

required

The number of units

total

string

required

The total fixed price (typically units × pricePerUnit)

tieredPricingModel

object

Required when type is tiered

Show TieredPricingModel Properties

tiers

array

required

Array of pricing tiers

Show PricingTier Properties

minUnits

integer

required

The minimum number of units for this tier

maxUnits

integer

The maximum number of units for this tier (null for unlimited upper bound)

pricePerUnit

string

The price charged per unit in this tier

fixedFee

string

Any fixed fee charged for this tier

graduatedTieredPricingModel

object

Required when type is graduated_tiered

Show GraduatedTieredPricingModel Properties

tiers

array

required

Array of pricing tiers

Show PricingTier Properties

minUnits

integer

required

The minimum number of units for this tier

maxUnits

integer

The maximum number of units for this tier (null for unlimited upper bound)

pricePerUnit

string

The price charged per unit in this tier

fixedFee

string

Any fixed fee charged for this tier

prepaidTieredPricingModel

object

Required when type is prepaid_tiered

Show PrepaidTieredPricingModel Properties

tiers

array

required

Array of pricing tiers

Show PricingTier Properties

minUnits

integer

required

The minimum number of units for this tier

maxUnits

integer

The maximum number of units for this tier (null for unlimited upper bound)

pricePerUnit

string

The price charged per unit in this tier

fixedFee

string

Any fixed fee charged for this tier

units

integer

required

The number of prepaid units

prepaidFixedTieredPricingModel

object

Required when type is prepaid_fixed_tiered

Show PrepaidFixedTieredPricingModel Properties

tiers

array

required

Array of pricing tiers

Show PricingTier Properties

minUnits

integer

required

The minimum number of units for this tier

maxUnits

integer

The maximum number of units for this tier (null for unlimited upper bound)

pricePerUnit

string

The price charged per unit in this tier

fixedFee

string

Any fixed fee charged for this tier

units

integer

required

The number of prepaid units

tieredPercentagePricingModel

object

Required when type is tiered_percentage

Show TieredPercentagePricingModel Properties

tiers

array

required

Array of graduated tiers

Show GraduatedTier Properties

minUnits

integer

required

The minimum number of units for this tier

maxUnits

integer

The maximum number of units for this tier (null for unlimited upper bound)

percentage

string

The percentage rate to charge in this tier

fixedFee

string

Any fixed fee charged for this tier

graduatedPercentagePricingModel

object

Required when type is graduated_percentage

Show GraduatedPercentagePricingModel Properties

tiers

array

required

Array of graduated tiers

Show GraduatedTier Properties

minUnits

integer

required

The minimum number of units for this tier

maxUnits

integer

The maximum number of units for this tier (null for unlimited upper bound)

percentage

string

The percentage rate to charge in this tier

fixedFee

string

Any fixed fee charged for this tier

volumePercentagePricingModel

object

Required when type is volume_percentage

Show VolumePercentagePricingModel Properties

pricePerUnit

string

required

The base price per unit

percentage

string

required

The percentage rate to charge

fixedFee

string

Optional fixed fee to charge

chargeOnContractStart

boolean

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.

API Reference

Billing Events & Usage Metering

Bundles

Credit Grants

Credit Notes

Customers

Invoices

Plans

Products

Refunds

Subscriptions

Subscription Versions

Wallets

Pricing Models API Reference

Supported Pricing Model Types

Request Examples

Required and Optional Fields

Common Configuration Options

Trial Periods

Spending Thresholds

Discounts

Field Reference

Using with Subscription Versions

​Supported Pricing Model Types

​Request Examples

​Required and Optional Fields

​Common Configuration Options

​Trial Periods

​Spending Thresholds

​Discounts

​Field Reference

​Using with Subscription Versions

Supported Pricing Model Types

Request Examples

Required and Optional Fields

Common Configuration Options

Trial Periods

Spending Thresholds

Discounts

Field Reference

Using with Subscription Versions