effective_from date. A published phase never changes, so the card keeps an exact history of every rate it has had and of when Alguna learned it. Use phases for every rate change: a price list update, a fee increase, or a fix to a wrong rate.
Rate cards are available on request. See Rate cards to turn them on. Requests carry
Authorization: Bearer with your API key and an Alguna-Version header.Draft, publish, supersede
A phase starts as a draft. A draft has no date and bills nothing. You can change a draft or delete it. When you publish it, you give it itseffective_from date and it becomes published. A published phase that a correction replaces becomes superseded.
Each phase also has a
number, in the order the phases were created.
“Scheduled”, “live” and “ended” are not statuses. Alguna works them out from the dates. A published phase is scheduled before its effective_from, live from that date until the next published phase starts, and ended after that.
Each published phase records who published it. A person’s publish records the person. An automatic publish from a source, and a copy on a follower card, record the source.
A phase sets only the entries it names
One phase can change any entries of the card at one date. An entry that the phase does not name keeps the model it had before the phase. So at every moment, every entry has exactly one model. Example: Token Standard has a usage entry and a platform fee. A phase from 16 Mar 2027 changes only the platform fee, from $500.00 to $600.00. The usage rates do not change on 16 Mar 2027, and no usage line splits on that date.Create and publish a phase
Create a draft with the entries it sets:matrix. Its dimensions must be dimensions that the entry declares. A fixed entry takes a fee, the flat amount for one billing period. To start from an existing phase, send base_phase_id and the draft copies that phase’s entries.
To change the draft, send PATCH /rate-card-phases/{id}. Its entries replace the models of the entries you name, and remove_entry_ids drops the draft’s change to those entries. To discard the draft, send DELETE /rate-card-phases/{id}. Alguna hides a deleted draft at once and deletes it for good after 90 days.
Publish the draft with its date:
expected_revision is optional. If you send it and the card’s revision is no longer that number, the publish fails with 409 and nothing changes. Read the card again, check the newer phase, and publish again.
The response is the published phase, plus issued_invoices_overlapping. That is the number of issued invoices whose billing period ends after the phase starts. Those invoices keep their rates. See Issued invoices keep their rates.
To read phases, send GET /rate-cards/{id}/phases or GET /rate-card-phases/{id}.
Correct a published phase
You cannot edit a published phase. To fix a wrong rate, publish a correction that supersedes it. Sendsupersedes_phase_id when you publish. The correction takes the date of the phase it replaces, and the replaced phase becomes superseded.
effective_from. A publish at the date of an existing published phase that does not supersede it fails with 409.
Example: Phase 3 sets orion-pro in us to $0.0000025 from 15 Oct 2026. The correct rate is $0.0000026. You publish phase 4 with supersedes_phase_id set to phase 3. Phase 4 starts on 15 Oct 2026, and phase 3 is superseded. A correction keeps every entry that its target set, so phase 4 also sets every other entry that phase 3 set.
The two clocks
Each published phase has two times:effective_from: when its rates apply.published_at: when Alguna learned them.
As known on 1 Oct 2026, a token used on 20 Sep 2026 costs $0.000003, because P2 was not published yet. As known on 5 Oct 2026, the same token costs $0.0000027.
Open invoices read the card as known now
When a phase publishes, Alguna reprices every open invoice of every subscription that uses the card. You do not refresh anything. Open invoices include drafts and invoices that are pending approval, scheduled or processing. If a repriced invoice was pending approval or approved and its amount changes, it goes back to pending approval. Nobody sends an amount that they did not see. Example: An invoice was approved at $1,000.00. A publish reprices it to $1,050.00. It is pending approval again.Issued invoices keep their rates
Alguna never re-rates an issued invoice. An issued invoice keeps the rates as known at its issue time. Anything that reads the issued period again, such as a minimum’s drawdown or revenue for the invoice, reads the card as known at that time too. When a phase published after the issue time covers part of the invoice’s period, the invoice line shows a note. The note says when the phase was published, the date its rates start, and that the invoice keeps the rates known when it was issued. Example: The September invoice issued on 1 Oct 2026 bills 10,000,000orion-pro tokens in us, all used after 15 Sep 2026, at $0.000003: $30.00. On 4 Oct 2026, P2 publishes at $0.0000027 from 15 Sep 2026. As known now, the usage costs $27.00. The issued invoice stays at $30.00 and shows the note. Alguna does not credit the $3.00 difference.
The publish response counts these invoices in issued_invoices_overlapping. The count includes issued, paid and overdue invoices with a line of a price on an entry the phase sets, where the line period ends after the phase starts. Void and canceled invoices do not count.
Usage across a phase change
A phase change does not split the billing cycle. Inside the cycle, Alguna measures usage in one window for each phase and rates each window with its own phase. The invoice gets one line for each window and cell. Example: The cycle is 1 Oct to 1 Nov 2026. A phase from 15 Oct 2026 12:00 changesorion-pro in us from $0.000003 to $0.0000025.
These rules apply:
- The boundary belongs to the new phase. A window includes its start and excludes its end, to the millisecond. An event at exactly 15 Oct 12:00:00.000 uses the new phase.
- Tiers carry across the split. Graduated tiers keep their position for each cell, and a tier fee is not charged twice. For example, with 0 to 1,000 units at $1.00 and then $0.50, 800 units before the split and 800 after cost $1,300.00, the same as with no split.
- Only the usage entry splits usage. A phase that changes only a fee adds no usage line.
- Rounding happens once per line. Rates keep full precision until the line total rounds to the currency’s minor unit.
Fees across a phase change
A fixed entry bills in advance, at the fee in force at the start of the billing cycle. Every item of the cycle uses that fee, mid-cycle proration items included. Example: The platform fee changes from $500.00 to $600.00 from 16 Mar 2027. A customer billed monthly on the 1st pays $500.00 for March and $600.00 for April. A customer whose cycle starts on the 16th pays $600.00 from 16 Mar 2027. A fee change inside a cycle is not prorated. The March cycle in the example bills $500.00, not a mix of the two fees.Dates
Any date is allowed
A phase can start in the past, today or in the future. A phase in the past changes open invoices only. Issued invoices keep their rates, and the publish tells you how many of them the phase overlaps. To publish a phase, with any date, you need the permission to manage rate cards. Without it, the publish fails with 403.A card price cannot start before the first phase
A card has no rates before the first phase of an entry. So Alguna refuses a card price that would start earlier. This applies when you add a card price to a subscription, move a subscription start earlier, or check out with such a price. Example: The first phase of Token Standard starts on 5 Oct 2026. A subscription from 1 Oct 2026 is refused: “Token Standard has no rates before 5 Oct 2026. Publish a phase from 1 Oct 2026, or start the subscription on 5 Oct 2026.” If the entry has no published phase at all, the message asks you to publish a phase from the start date.Related
- Rate cards: cards, entries and card prices.
- Sources: phases that a price list publishes or drafts.
- Followers: cards that copy each phase of another card.
- Unbilled usage: usage that no phase prices.