Pricing Models API Reference

Technical reference for implementing Alguna’s pricing models in your API calls

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.