Billing Milestones
Not available through the public API
This page describes a planned capability. It has no endpoints in the public API
today, and nothing on this page can be called. Until it ships, bill a milestone as a one-off charge: add it to a standalone draft invoice (POST /v1/invoices, then POST /v1/invoices/{id}/lines) and finalise it. A subscription phase can also end when a metric crosses a threshold (a phase ends of kind event; see Subscriptions).
A billing milestone would carve out a percentage of a subscription's contract value and bill it as a one-shot invoice line when the milestone is triggered: project-style billing (25% on kickoff, 50% on delivery, 25% on acceptance), date-pinned releases, or captures driven by an external event, each invoice line tied back to the milestone for audit.
Planned model
The fields below describe the planned shape. They are not part of any API today and may change before release.
A milestone would always be scoped to a subscription, and its percentage would carve out a slice of that subscription's contract value.
| Field | Description |
|---|---|
subscription_id | The subscription this milestone belongs to. |
product_id | The product line this milestone bills against. |
name | Human-readable label that appears on the invoice line. |
description | Optional longer description. |
percentage | Decimal fraction of the subscription's contract value, greater than 0 and at most 1 (e.g. 0.25 for 25%). |
trigger_type | MANUAL, DATE, or EVENT. |
trigger_date | Calendar date, for DATE triggers. |
status | PENDING, TRIGGERED, INVOICED. |
triggered_at | Set when the milestone fires. |
invoice_id | The invoice the resulting line landed on. |
Planned trigger types
trigger_type | Fires when |
|---|---|
MANUAL | An operator triggers it. |
DATE | trigger_date passes. |
EVENT | A signed call from an external system reports the event. |
Planned rules
- The summed
percentageof all milestones on a subscription product could not exceed 100%. - Only a pending milestone could trigger, and a milestone whose line already landed on a finalised invoice could not trigger again.
Next steps
- Subscriptions - phases, including phases that end on an event.
- Invoices - standalone draft invoices and manual charges.