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:
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) |
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
Spending Thresholds
Discounts
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:
Optional number of trial days before billing begins for this price
Optional minimum spending threshold for this price
Optional maximum spending threshold for this price
Optional discount to apply to this price
The billing interval for this price. Possible values:
monthly, quarterly, yearly
Required when type is unit
Required when type is fixed
Required when type is tiered
Required when type is graduated_tiered
Required when type is prepaid_tiered
Required when type is prepaid_fixed_tiered
Required when type is tiered_percentage
Required when type is graduated_percentage
Required when type is volume_percentage
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.