Documentation Index
Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
When creating or viewing subscription items, each item has a price object containing a type field that determines which pricing model is used. Exactly one pricing model field will be populated, matching the type.
Supported Pricing Types
| Type | Fee Type | Model Field | Description |
|---|
unit | metered | unit_pricing_model | Simple per-unit rate |
fixed | fixed | fixed_pricing_model | Flat amount for a fixed quantity |
tiered | metered | tiered_pricing_model | Total usage determines the tier; all units priced at that tier’s rate |
graduated_tiered | metered | graduated_tiered_pricing_model | Each tier priced independently (units 0-100 at rate A, 101-500 at rate B) |
tiered_percentage | metered | tiered_percentage_pricing_model | Percentage-based tiers (first matching tier applies) |
graduated_percentage | metered | graduated_percentage_pricing_model | Graduated percentage tiers (each tier priced independently) |
volume_percentage | metered | volume_percentage_pricing_model | Percentage of transaction volume with base rate |
prepaid_tiered | metered | prepaid_tiered_pricing_model | Pre-purchased units with tiered overage rates |
prepaid_fixed_tiered | metered | prepaid_fixed_tiered_pricing_model | Pre-purchased units with tiered overages and configurable overage interval |
expression | metered | expression_pricing_model | Custom expression-based pricing |
Common Fields
Every price includes these fields alongside the model-specific field:
| Field | Type | Required | Description |
|---|
type | string | Yes | One of the 10 pricing types above |
billing_interval | string | Yes | monthly, quarterly, semi_annual, or yearly |
fee_type | string | Yes | fixed or metered |
billing_direction | string | Yes | advance (start of period) or arrears (end of period) |
billing_frequency | string | No | recurring or one-off. Required for fixed fee type |
metric_ids | string[] | Conditional | Required for metered fee type. Which metrics drive usage |
display_order | integer | No | Sort order for display |
charge_on_contract_start | boolean | No | For one-off prices: charge on contract start instead of first billing date |
trial_period_days | integer | No | Days before billing starts (minimum 1) |
discount | object | No | Price-level discount |
minimum_spend | object | No | Floor spend per period ({ "amount": "500.00", "period": "monthly" }) |
maximum_spend | object | No | Ceiling spend per period ({ "amount": "5000.00", "period": "monthly" }) |
When creating prices, currency is inherited from the subscription and should not be specified. In responses, currency is always included.
Pricing Model Examples
Unit Pricing
Simple per-unit rate. Best for metered products where each unit costs the same.
{
"type": "unit",
"billing_interval": "monthly",
"fee_type": "metered",
"billing_direction": "arrears",
"metric_ids": ["met_api_calls"],
"unit_pricing_model": {
"price_per_unit": "0.05"
}
}
Fixed Pricing
Flat amount for a fixed quantity of units. total is computed server-side (not required in requests).
{
"type": "fixed",
"billing_interval": "monthly",
"fee_type": "fixed",
"billing_direction": "arrears",
"billing_frequency": "recurring",
"fixed_pricing_model": {
"price_per_unit": "500.00",
"units": 1
}
}
total field is included:
"fixed_pricing_model": {
"price_per_unit": "500.00",
"units": 1,
"total": "500.00"
}
Tiered Pricing
Total usage determines which tier applies. All units are priced at that single tier’s rate.
{
"type": "tiered",
"billing_interval": "monthly",
"fee_type": "metered",
"billing_direction": "arrears",
"metric_ids": ["met_api_calls"],
"tiered_pricing_model": {
"tiers": [
{ "min_units": 0, "max_units": 1000, "price_per_unit": "0.20", "fixed_fee": null },
{ "min_units": 1001, "max_units": 10000, "price_per_unit": "0.15", "fixed_fee": null },
{ "min_units": 10001, "max_units": null, "price_per_unit": "0.10", "fixed_fee": null }
]
}
}
Graduated Tiered Pricing
Each tier is priced independently. Units 0-1000 at 0.20,units1001−10000at0.15, etc.
{
"type": "graduated_tiered",
"billing_interval": "monthly",
"fee_type": "metered",
"billing_direction": "arrears",
"metric_ids": ["met_api_calls"],
"graduated_tiered_pricing_model": {
"tiers": [
{ "min_units": 0, "max_units": 1000, "price_per_unit": "0.20", "fixed_fee": null },
{ "min_units": 1001, "max_units": 10000, "price_per_unit": "0.15", "fixed_fee": null },
{ "min_units": 10001, "max_units": null, "price_per_unit": "0.10", "fixed_fee": null }
]
}
}
Tiered Percentage Pricing
Percentage-based tiers. Total usage determines which tier’s percentage applies to all units.
{
"type": "tiered_percentage",
"billing_interval": "monthly",
"fee_type": "metered",
"billing_direction": "arrears",
"metric_ids": ["met_revenue"],
"tiered_percentage_pricing_model": {
"tiers": [
{ "min_units": 0, "max_units": 100000, "percentage": "2.9", "fixed_fee": "0.30" },
{ "min_units": 100001, "max_units": null, "percentage": "1.5", "fixed_fee": null }
]
}
}
Graduated Percentage Pricing
Each tier’s percentage applies independently to the units within that tier.
{
"type": "graduated_percentage",
"billing_interval": "monthly",
"fee_type": "metered",
"billing_direction": "arrears",
"metric_ids": ["met_revenue"],
"graduated_percentage_pricing_model": {
"tiers": [
{ "min_units": 0, "max_units": 100000, "percentage": "2.9", "fixed_fee": "0.30" },
{ "min_units": 100001, "max_units": null, "percentage": "1.5", "fixed_fee": null }
]
}
}
Volume Percentage Pricing
Charges a percentage of transaction volume plus an optional fixed fee per transaction.
{
"type": "volume_percentage",
"billing_interval": "monthly",
"fee_type": "metered",
"billing_direction": "arrears",
"metric_ids": ["met_payments"],
"volume_percentage_pricing_model": {
"price_per_unit": "0.00",
"percentage": "2.9",
"fixed_fee": "0.30"
}
}
Prepaid Tiered Pricing
Customer pre-purchases a block of units. Overages are charged at tiered rates.
{
"type": "prepaid_tiered",
"billing_interval": "monthly",
"fee_type": "metered",
"billing_direction": "arrears",
"metric_ids": ["met_api_calls"],
"prepaid_tiered_pricing_model": {
"prepaid_units": 50000,
"tiers": [
{ "min_units": 0, "max_units": 10000, "price_per_unit": "0.02", "fixed_fee": null },
{ "min_units": 10001, "max_units": null, "price_per_unit": "0.01", "fixed_fee": null }
]
}
}
Prepaid Fixed Tiered Pricing
Like prepaid tiered, but with a configurable overage charge interval.
{
"type": "prepaid_fixed_tiered",
"billing_interval": "monthly",
"fee_type": "metered",
"billing_direction": "arrears",
"metric_ids": ["met_api_calls"],
"prepaid_fixed_tiered_pricing_model": {
"prepaid_units": 50000,
"overages_charge_interval": "monthly",
"tiers": [
{ "min_units": 0, "max_units": 10000, "price_per_unit": "0.02", "fixed_fee": null },
{ "min_units": 10001, "max_units": null, "price_per_unit": "0.01", "fixed_fee": null }
]
}
}
Expression Pricing
Custom expression-based pricing. Supports arbitrary formulas for quantity and unit price.
{
"type": "expression",
"billing_interval": "monthly",
"fee_type": "metered",
"billing_direction": "arrears",
"metric_ids": ["met_compute_hours"],
"expression_pricing_model": {
"charges": [
{
"billing_direction": "charge",
"description": "Compute usage charge",
"quantity_expression": "usage.compute_hours",
"unit_price_expression": "0.01 * (1 - min(usage.compute_hours / 100000, 0.5))"
}
]
}
}
Discounts
Price-level discounts support both percentage and fixed types:
"discount": {
"type": "percentage",
"amount": "20",
"duration_type": "fixed",
"duration_value": 3,
"duration_unit": "months"
}
| Field | Type | Required | Description |
|---|
type | string | Yes | percentage or fixed |
amount | string | Yes | Discount amount (percentage value or fixed amount) |
duration_type | string | Yes | fixed, rolling, or perpetual |
duration_value | integer | Conditional | Required when duration_type is fixed |
duration_unit | string | Conditional | Required when duration_type is fixed. Values: days, weeks, months, years |
Subscription-level discounts (set via PATCH) only support percentage type. Price-level discounts support both types.
Spending Thresholds
Both minimum_spend and maximum_spend use the same structure:
{
"amount": "500.00",
"period": "monthly"
}
| Field | Type | Required | Description |
|---|
amount | string | Yes | Threshold amount (must be greater than 0) |
period | string | Yes | Billing period: monthly, quarterly, semi_annual, or yearly |
Tier Structure
Standard Tiers (unit-based pricing models)
Used by tiered, graduated_tiered, prepaid_tiered, and prepaid_fixed_tiered models:
| Field | Type | Required | Description |
|---|
min_units | integer | Yes | Lower bound of the tier (inclusive) |
max_units | integer | No | Upper bound (null = unlimited) |
price_per_unit | string | No | Price charged per unit in this tier |
fixed_fee | string | No | Fixed fee charged when this tier is active |
Percentage Tiers
Used by tiered_percentage and graduated_percentage models:
| Field | Type | Required | Description |
|---|
min_units | integer | Yes | Lower bound of the tier (inclusive) |
max_units | integer | No | Upper bound (null = unlimited) |
percentage | string | No | Percentage rate applied in this tier |
fixed_fee | string | No | Fixed fee charged when this tier is active |
