> ## 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.

# Rate cards

> A rate card holds dated usage rates and fees that many prices share, so one publish changes the rates of every subscription that uses the card. Available on request.

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](https://alguna.com/docs/pricing/pricing-models.md) on the price. For where prices sit in the object graph, see [How Alguna works](https://alguna.com/docs/concepts/how-alguna-works.md).

> [!NOTE]
>
> Rate cards are available on request. Contact [support@alguna.io](mailto: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](https://alguna.com/docs/rate-cards/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](https://alguna.com/docs/rate-cards/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.

| Kind | What it prices | Model | Billing |
| - | - | - | - |
| `usage` | Events of one metric | A matrix: a rate for each combination of dimension values | In arrears, at the cadence of the price |
| `fixed` | A flat recurring fee | One amount per billing period | In advance, at the cadence of the entry |

### 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](https://alguna.com/docs/api-reference/v2/subscriptions/pricing-models.md#matrix-pricing) 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](https://alguna.com/docs/rate-cards/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

```text theme={null}
POST /rate-cards
```

```json theme={null}
{
  "name": "Token Standard",
  "currency": "USD",
  "entries": [
    {
      "product_id": "prod_032wMej82trlC5RulBsDJY",
      "name": "Tokens",
      "kind": "usage",
      "dimensions": [
        { "key": "model", "label": "Model", "values": ["orion-pro", "orion-mini"] },
        { "key": "region", "label": "Region", "values": ["us", "eu"] }
      ]
    },
    {
      "product_id": "prod_04ab8Nej82trlC5RulBsDJY",
      "name": "Platform fee",
      "kind": "fixed",
      "billing_period": { "unit": "month", "count": 1 }
    }
  ]
}
```

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.

```json theme={null}
{
  "type": "rate_card",
  "fee_type": "metered",
  "billing_direction": "arrears",
  "billing_interval_unit": "month",
  "billing_interval_count": 1,
  "metric_ids": ["mtr_032wMej82trlC5RulBsDJY"],
  "rate_card_pricing_model": {
    "rate_card_id": "rcd_0000000000000001",
    "entry_id": "rcde_0000000000000001"
  }
}
```

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](https://alguna.com/docs/rate-cards/phases#a-card-price-cannot-start-before-the-first-phase).
* 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.

| Model | Region | Rate per token |
| - | - | - |
| `orion-pro` | `us` | \$0.000003 |
| `orion-pro` | `eu` | \$0.0000033 |
| `orion-mini` | `us` | \$0.0000005 |
| `orion-mini` | `eu` | \$0.00000055 |

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.

| Line | Calculation | Amount |
| - | - | - |
| Tokens, `orion-pro` / `us` | 10,000,000 × \$0.000003 | \$30.00 |
| Tokens, `orion-mini` / `eu` | 4,000,000 × \$0.00000055 | \$2.20 |
| Platform fee | 1 × \$500.00 | \$500.00 |
| **Total** | | **\$532.20** |

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](https://alguna.com/docs/rate-cards/sources).
* Another rate card, plus a markup. See [Followers](https://alguna.com/docs/rate-cards/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](https://alguna.com/docs/rate-cards/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](https://alguna.com/docs/rate-cards/phases#issued-invoices-keep-their-rates).
* 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](https://alguna.com/docs/rate-cards/followers).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.