Skip to main content
Milestone billing is rolled out per organization. If a one-off product row in your subscription builder has no “Bill on” choice, contact Alguna to enable it.
A one-off charge normally bills on the contract start date or the first billing date. Some charges are agreed against an event instead: an implementation fee billed on go-live, hardware billed on shipment, a licence billed on acceptance. Milestone billing keeps those charges on the quote, holds them off the billing schedule until the milestone is reached, and invoices them the day it is marked reached. Everything else about the charge stays the same: it is a one-off price on the subscription, it appears on the quote the customer signs, and once invoiced it follows the normal invoice lifecycle. For the date-based behaviour of one-off prices see Recurring Invoices; for invoices you create by hand see One-Off Invoices.

​
How it works

  1. The price names a milestone. A one-off, fixed price carries a milestone_key such as go_live. In the subscription builder every one-off product row has a Bill on choice: the contract or billing start date, or a milestone from your organization’s catalog. Typing a new name adds it to the catalog, so every subscription names the same milestone the same way.
  2. The quote shows the trigger. The billing column reads “On Go Live” instead of “One-time”, so the customer signs the term they agreed to.
  3. The schedule waits. While the milestone is pending, the price produces no entry on the billing schedule and no invoice. The subscription page lists the milestones with their expected dates. A one-off charge that was built to bill on a date can still be moved onto a milestone there with Add milestone, as long as it has not been invoiced.
  4. Marking it reached releases the charge. An operator marks the milestone reached in the dashboard, or an external system calls the API. The charge is placed on the schedule and invoiced through the subscription’s usual settings: auto-issue, approvals and delivery apply as they do to any other invoice. By default it is invoiced that day; the subscription can hold it for the next scheduled invoice instead.
A milestone can only be reached on an active subscription, and only when one of the subscription’s prices bills on it.

​
Two dates

Marking a milestone reached records two dates. The invoice is never backdated: a shipment confirmed a week late is invoiced today with last week’s service date. Issue promptly after the event, since the invoice date is what tax and payment terms run from.

​
Invoice on the next scheduled invoice

Some customers reconcile one invoice per billing period and do not want a separate invoice each time a milestone is reached. On the subscription’s Invoicing tab, set Milestone charges to Add to next scheduled invoice. Only the invoice date moves. The service date on the line and the revenue recognition date stay the day the milestone was reached. If nothing else is scheduled to bill on or after that day, for example a subscription made only of milestone charges, the charge is invoiced the day it is marked reached so it is never left unbilled. A held charge can still be reopened until its invoice is issued. Changing the setting moves charges that are not yet invoiced; charges already on an issued invoice stay where they are.

​
Setting it up

​
Add a milestone to a price

In the quote or subscription builder, set a product’s billing frequency to One-off and choose a milestone under Bill on. Pick one from the catalog or type a new name to add it; the key is derived from the name (UAT sign-off becomes uat_sign_off). Leave the field at Contract or billing start date for a one-off price that bills on a date. Through the API, set milestone_key on the price. A milestone key cannot be combined with charge_on_contract_start, and only a one-off, fixed price can carry one.

​
Track and reach milestones

The subscription page lists every milestone the subscription’s prices bill on, with the charges it releases and their total. From there you can:
  • Set an expected date. Forecasting only: it never triggers billing.
  • Mark reached. Choose the reached date and an optional note, such as a shipment reference. The charge is invoiced today.
  • Reopen. Returns the milestone to pending while its invoice is still a draft. Once the invoice is issued, correct it with a credit note instead.

​
Through the API

List a subscription’s milestones:
cURL
Mark one reached. reached_at is optional and defaults to today; the call is safe to retry, because a milestone already reached is returned unchanged rather than billed again.
cURL
Each milestone in the response carries its status (pending or reached), its dates, and the price_ids it releases.

​
Limits

  • A milestone bills all of its charges at once. Billing a quantity per shipment, such as four of nine devices, is not supported yet.
  • Only a one-off, fixed price can bill on a milestone. Metered and recurring prices bill on their period.
  • An expected date that passes does not alert anyone or bill automatically.
  • Add to next scheduled invoice is set per subscription in the dashboard; it is not yet available through the public API.