Configure Products - Alguna Docs

A product is the thing you sell: a platform fee, a seat, an API call, an implementation package. It declares how the thing is charged, not how much. The amount lives on a price, which attaches to the product inside a plan, a quote, or a subscription. Create products first; everything downstream (plans, quotes, subscriptions, invoice lines, revenue schedules) refers back to them. See How Alguna Works for where products sit in the object graph.

What a product declares

Field	Values	Meaning
`fee_type`	`fixed`, `metered`	Charged at a set quantity, or by measured usage
`billing_frequency`	`recurring`, `one-off`	Charged every period, or once. Required for fixed products; metered products are always recurring
`payment_terms`	`advance`, `arrears`	Billed before the period starts, or after it ends. Metered products must be `arrears`
`metric_ids`	Metric IDs	The billable metrics that measure a metered product

Products are currency-neutral. A price carries the currency of the plan or subscription it belongs to, so the same product can be sold in several currencies without being duplicated.

Create a product

In the dashboard

Go to Products and click New Product
Choose the fee type, billing frequency and payment terms
Fill in the details below and click Save

Via the API

Use Create a product (POST /products).

curl -X POST https://api.alguna.io/products \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Platform Fee",
    "sku": "PLATFORM_FEE",
    "fee_type": "fixed",
    "billing_frequency": "recurring",
    "payment_terms": "advance",
    "revenue_allocation_method": "straight_line"
  }'

import os

import requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.alguna.io/products",
    headers=HEADERS,
    json={
        "name": "Platform Fee",
        "sku": "PLATFORM_FEE",
        "fee_type": "fixed",
        "billing_frequency": "recurring",
        "payment_terms": "advance",
        "revenue_allocation_method": "straight_line",
    },
    timeout=10,
)
response.raise_for_status()
product = response.json()
print(product["id"])

A metered product links to the metrics that measure it and is always billed in arrears:

curl -X POST https://api.alguna.io/products \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Requests",
    "fee_type": "metered",
    "payment_terms": "arrears",
    "metric_ids": ["mtr_032wMej82trlC5RulBsDJY"],
    "unit_label_singular": "request",
    "unit_label_plural": "requests",
    "revenue_allocation_method": "usage_based"
  }'

import os

import requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.alguna.io/products",
    headers=HEADERS,
    json={
        "name": "API Requests",
        "fee_type": "metered",
        "payment_terms": "arrears",
        "metric_ids": ["mtr_032wMej82trlC5RulBsDJY"],
        "unit_label_singular": "request",
        "unit_label_plural": "requests",
        "revenue_allocation_method": "usage_based",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json()["id"])

Fee types

Fixed

A set quantity at a set rate each period: platform access, seat licences, support tiers. The quantity is fixed on the price (for example 25 seats), not measured.

Metered

Charged on what the customer actually consumed: API requests, data transfer, compute hours, storage. A metered product needs at least one billable metric, and usage arrives through POST /events.

Metered products are billed in arrears because the amount is only known once the period has been metered. Prepaid commitments (the prepaid_tiered and prepaid_fixed_tiered price types) are the exception: the committed amount is billed in advance and drawn down, with any overage billed in arrears.

Payment terms

advance — the charge is issued at the start of the period. A $99 platform fee for January is invoiced on 1 January.
arrears — the charge is issued at the end of the period. January’s usage is invoiced on 1 February.

The same two values appear on every price as billing_direction. Mid-period changes to advance charges are prorated; arrears charges are not, because their measurement window already bounds them.

Billing frequency

recurring — charged every billing period. The interval itself (monthly, quarterly, semi-annual, yearly) is set on the price, not the product.
one-off — charged once and never again. Use it for setup fees, implementation, or training. A one-off price can be charged on the contract start date rather than the first billing date with charge_on_contract_start.

Pricing models

A price turns a quantity into an amount. Alguna has eleven price types; the ones you will reach for most often are below. Pricing Models covers the full set with worked examples, and the pricing models reference has the request shape for each.

Type	Behaviour
`fixed`	A flat amount for a fixed quantity, regardless of usage. $99/month for platform access.
`unit`	One rate multiplied by the quantity. $10/seat × 25 seats =$ 250.
`tiered`	The total quantity picks a tier, and every unit is priced at that tier’s rate.
`graduated_tiered`	Each tier is priced independently, so the quantity is split across the tiers it spans.
`prepaid_tiered`, `prepaid_fixed_tiered`	A committed quantity billed up front, with overage tiers beyond it.
`tiered_percentage`, `graduated_percentage`, `volume_percentage`	A percentage of a transaction value rather than a per-unit rate.
`expression`, `matrix`	A formula over metrics, or a lookup by event properties, for pricing the standard models cannot express.

tiered and graduated_tiered use the same tier table and produce different amounts. For 250 units on tiers of

1.00 (0–100),

0.80 (101–500) and

0.50 (501+): tiered gives 250 ×

0.80 = $200**; graduated gives (100 ×$ 1.00) + (150 × $0.80) = **$ 220. Check which one you have selected before publishing.

Product details

Field	Description
`name`	Display name shown on invoices and quotes
`description`	Longer description shown on quotes
`sku`	Your product code, passed to ERP and revenue recognition systems
`tax_code`	Provider-neutral tax code used when tax is calculated. Omit for standard-rated. See Tax
`revenue_allocation_method`	`straight_line`, `usage_based` or `contract_level_straight_line`. Controls how the charge is spread across a period for revenue recognition
`unit_label_singular`, `unit_label_plural`	What a unit is called on documents (for example “request” / “requests”). Defaults to “unit” / “units”
`tag_ids`	Tags for filtering and reporting

Everything except fee_type, billing_frequency, payment_terms and metric_ids can be changed later with Update a product (PATCH /products/{id}). The charging shape is fixed once the product exists; create a new product if it needs to change.

Common product patterns

SaaS platform

Product	`fee_type`	`billing_frequency`	Typical price type
Platform access	`fixed`	`recurring`	`fixed`
User seats	`fixed`	`recurring`	`unit`
API overage	`metered`	`recurring`	`graduated_tiered`

Infrastructure

Product	`fee_type`	`billing_frequency`	Typical price type
Compute hours	`metered`	`recurring`	`tiered`
Storage (GB)	`metered`	`recurring`	`unit`
Data transfer	`metered`	`recurring`	`matrix` (rate by region)

Professional services

Product	`fee_type`	`billing_frequency`	Typical price type
Implementation	`fixed`	`one-off`	`fixed`
Consulting hours	`fixed`	`one-off`	`unit`
Support package	`fixed`	`recurring`	`fixed`

Managing products

Edit a product

In the dashboard, open the product and click Save after making changes; via the API, use Update a product.

Editing a product changes its name, description and metadata everywhere it appears. Amounts are not on the product: to change what a customer pays, edit the price on the plan or amend the subscription.

Delete a product

Delete a product (DELETE /products/{id}) soft-deletes it. A product that is on an active subscription cannot be deleted; remove it from those subscriptions first, or leave it in place and stop adding it to new plans.

Bundles

A bundle groups several priced products so they can be added to a plan, quote or subscription as one item. Create one with Create a product bundle (POST /bundles).

Troubleshooting

Metered product shows no usage — confirm the product’s metric_ids match the metric your events map to, that events are being accepted by POST /events (check the failed array in the response), and that event timestamps fall inside the billing period. Pricing not calculating — check the tier table for gaps or overlaps between max_units and the next min_units, and that the price currency matches the customer’s currency. Product cannot be deleted — it is on an active subscription. Delete is a soft-delete and is refused while the product is in use.

Next steps

Pricing Models

All eleven price types, with worked examples.

Plans

Package products and prices into a reusable offer.

Define Metrics

Measure usage for metered products.

How Alguna Works

Where products sit in the quote-to-cash chain.

​What a product declares

​Create a product

​In the dashboard

​Via the API

​Fee types

​Fixed

​Metered

​Payment terms

​Billing frequency

​Pricing models

​Product details

​Common product patterns

​SaaS platform

​Infrastructure

​Professional services

​Managing products

​Edit a product

​Delete a product

​Bundles

​Troubleshooting

​Next steps

Pricing Models

Plans

Define Metrics

How Alguna Works

What a product declares

Create a product

In the dashboard

Via the API

Fee types

Fixed

Metered

Payment terms

Billing frequency

Pricing models

Product details

Common product patterns

SaaS platform

Infrastructure

Professional services

Managing products

Edit a product

Delete a product

Bundles

Troubleshooting

Next steps