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

# Milestone Billing

> Bill a one-off charge when a milestone is reached, such as go-live or shipment, instead of on a date

> [!NOTE]
>
> 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](https://alguna.com/docs/invoices/recurring-invoices.md); for invoices you create by hand see [One-Off Invoices](https://alguna.com/docs/invoices/one-off-invoices.md).

***

## 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, a one-off product's line has a **Bill on** choice under Billing: the contract or billing start date, or a milestone from your organization's catalog. **Add milestone** at the foot of that list adds a new name 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](#invoice-on-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.

| Date | What it is | Where it shows |
| - | - | - |
| Reached on | The day the milestone was actually reached. It may be backdated as far as the contract start, never set in the future. | The service date on the invoice line and the revenue recognition date. |
| Marked on | The day the milestone was declared reached. | The invoice date. |

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

| Setting | When a milestone is marked reached |
| - | - |
| Invoice when reached (default) | The charge is invoiced that day, on an invoice of its own unless another charge already bills that day. |
| Add to next scheduled invoice | The charge waits for the subscription's next scheduled invoice on or after that day and is billed on it, alongside the period's recurring and usage charges. |

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, open the product's line and, under **Billing**, choose a milestone from **Bill on**. The row only appears for a fixed one-off charge. Pick one from the catalog, or choose **Add milestone** at the foot of the list and name the new one; 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. The line then reads "On Go live" in the pricing table and on the quote.

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:

```bash cURL theme={null}
curl https://api.alguna.io/subscriptions/sub_abc123/milestones \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"
```

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.

```bash cURL theme={null}
curl -X POST https://api.alguna.io/subscriptions/sub_abc123/milestones/shipment/complete \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "reached_at": "2026-03-10",
    "note": "Shipment DHL-4471"
  }'
```

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.


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