Skip to main content
A rate card is one set of rates that many prices share. Each price points at one entry on the card, and the card decides the rate. When you publish new rates on the card, every subscription that uses it bills the new rates from the date you choose. You do not edit each price. Use a rate card when rates change often, when another system owns them, or when many plans and contracts must bill the same rates. A typical case is a token price list: one rate for each model in each region, changed every few weeks. If a rate belongs to one plan and rarely changes, use a normal pricing model on the price. For where prices sit in the object graph, see How Alguna works.
Rate cards are available on request. Contact support@alguna.io or your shared Slack channel to turn them on for your organization. Requests carry Authorization: Bearer with your API key and an Alguna-Version header.

​
Cards

A card has a name, one currency and one or more entries.
  • One currency. You set the currency when you create the card. It never changes. Every price that uses the card bills in that currency. A USD card cannot price a EUR plan.
  • Name. You can rename a card at any time.
  • No delete. You cannot delete a card. Its phases stay as the history of what each invoice billed.
  • Revision. The card’s revision goes up by one each time a phase publishes on it. Send it back as expected_revision when you publish, so a publish fails if someone else published first. See Phases.
The rates themselves live in phases. A phase is a dated set of rates for one or more entries. A published phase never changes. To change a rate, you publish a new phase. See Phases.

​
Entries

An entry is one product that the card prices. A card has at most one usage entry and one fixed entry for each product.

​
Usage entries

A usage entry declares its dimensions. A dimension is an event property key, such as model or region. Each phase gives the entry a matrix over those dimensions. Each cell of the matrix is one combination of values, such as model=orion-pro and region=eu, with its own pricing model. A cell takes any model that a matrix cell takes, for example a unit rate, graduated tiers or a percentage. When an event arrives, Alguna reads its properties and finds the cell that matches. Usage that matches no cell is never billed silently. See Unbilled usage.

​
Fixed entries

A fixed entry is one flat fee per billing period, for example a platform fee of $500.00 a month. The entry sets the billing period, and every price on the entry must bill at that cadence. The price’s quantity multiplies the fee, so a seat fee works the same way. A fixed entry bills in advance, at the fee in force at the start of the billing cycle. If the fee changes in the middle of a cycle, the whole cycle bills at the old fee. The next cycle bills at the new fee.

​
Create a card

A usage entry takes dimensions and no billing_period. A fixed entry takes a billing_period and no dimensions. To add an entry later, send one entry to POST /rate-cards/{id}/entries. The other card endpoints are GET /rate-cards, GET /rate-cards/{id} and PATCH /rate-cards/{id}, which changes the name only. A new card has no rates until you publish its first phase.

​
Point a price at an entry

A price uses the card when its type is rate_card. The price names the card and one entry, and carries no pricing model of its own.
Alguna checks the price against the entry when you save it:
  • The price’s product must be the entry’s product, and its currency must be the card’s currency.
  • A price on a usage entry is metered, billed in arrears and recurring. It has exactly one metric, and the metric sums or counts.
  • A price on a fixed entry is fixed and billed in advance. It has no metrics. A recurring price’s cadence must equal the entry’s billing period. A one-off price (a setup fee) bills the entry’s fee once, at the rate in force when it is charged.
  • A price cannot start before the first phase of its entry. See Phases.
  • A price’s card and entry never change. To move a subscription to another card, add a new price.

​
Example: one month on Token Standard

Phase 1 of Token Standard sets these rates. The rates are per token. The platform fee is $500.00 a month. A customer uses 10,000,000 orion-pro tokens in us and 4,000,000 orion-mini tokens in eu in November. Rates keep full precision. Each invoice line rounds once, to the currency’s minor unit.

​
Where the rates come from

You can write each phase by hand, in the dashboard or with the API. A card can also take its rates from one source:
  • A price list that Alguna fetches from a URL, that your system pushes, or that you upload. See Sources.
  • Another rate card, plus a markup. See Followers.
On a card that a source prices, you can pin a cell to keep your own rate while the source changes the rest. See Pins.

​
Limits

  • A fee change inside a billing cycle is not prorated. The whole cycle bills at the fee in force at its start.
  • Fixed entries bill in advance only. An arrears fee cannot use a card.
  • An issued invoice is never corrected. A later phase shows a note on the invoice and does not credit or re-bill it. See Phases.
  • Usage that arrives after its invoice is issued is not billed. This applies to all usage in Alguna.
  • A follower cannot set a different markup for each entry. See Followers.