Billing Subscriptions
A billing subscription represents a recurring billing agreement between a tenant and a customer. It defines who is being billed, when billing cycles occur, and what the current subscription status is.
Subscriptions do not directly define what is being billed — that is the role of subscription lines. A single subscription can contain multiple lines, each referencing a different PCM price.
Key relationships
- Customer — the subscription links to a FAR customer record (the party being billed)
- Customer site — optionally narrows billing to a specific customer site
- Contact point — references a PRM party contact point for the billing address
Subscription status lifecycle
Subscriptions progress through a defined set of statuses:
| Status | Meaning |
|---|---|
| PENDING | Subscription is being configured. Lines can be added or modified. |
| BILLABLE | Subscription is active and ready for invoice generation. |
| CHANGED | Subscription has been modified after activation. |
| PAYMENT_PENDING | An invoice has been generated and payment is awaited. |
| CLOSED | Subscription is terminated. No further billing occurs. |
What happens when a subscription becomes billable
When a subscription's status changes to BILLABLE, the system automatically queues an asynchronous job to generate the billing invoice. This means invoice generation is not instantaneous — it is processed in the background by the billing engine.
Line modification protection
Subscription lines can only be added or updated when the parent subscription has status PENDING. This protection prevents active subscriptions from having their line items changed unexpectedly.
Billing cycle configuration
The billing cycle is defined by time-component fields that specify when billing should occur in the customer's local time:
| Field | Purpose |
|---|---|
| Month | Month of the year (1–12) |
| Day of month | Day of the month (1–31) |
| Day of week | Day of the week (0 = Sunday, 6 = Saturday) |
| Hour | Hour (0–23) |
| Minute | Minute (0–59) |
| Second | Second (0–59) |
All cycle fields default to the current timestamp at the time of subscription creation.
Timezone handling
Each subscription stores its UTC offset in minutes (for example, NZST = 720, UTC = 0). This allows the billing engine to calculate cycle boundaries in the customer's local time.
Billing period tracking
The subscription tracks its current billing period with start and end timestamps. The end date is initially null and is calculated when the billing cycle runs.
Cancellation
Subscriptions support a structured cancellation flow with the following elements:
| Field | Purpose |
|---|---|
| Cancellation effective date | When the cancellation takes effect (must be on or after the current billing period start) |
| Cancellation request date | Automatically set when cancellation is initiated |
| Cancellation request reason | Free-text reason for cancellation |
| Final invoice action | How to handle the final billing period |
Final invoice actions
| Action | Meaning |
|---|---|
| CYCLE_END | Bill for the full cycle; cancellation takes effect at cycle end (default) |
| PRORATE_CYCLE_END | Prorate the charge; cancellation takes effect at cycle end |
| PRORATE_IMMEDIATE | Prorate the charge; cancellation takes effect immediately |
| IMMEDIATE | No final charge; cancellation takes effect immediately |
Subscription lines
Each subscription contains one or more lines. A line defines what is being billed by referencing a PCM price and specifying a subscribed quantity (defaulting to 1).
Consistency enforcement
All lines within a single subscription must share the same currency and billing interval (as defined on their referenced PCM prices). This prevents a subscription from mixing, for example, monthly USD prices with annual NZD prices.
Customer ID inheritance
The customer ID on subscription lines is automatically inherited from the parent subscription. It cannot be changed directly on the line — any attempt to update it is silently ignored.
Authorisation
Access to billing subscriptions is controlled through the linked customer:
- Viewing requires viewer access to the associated FAR customer
- Creating or editing requires editor access to the associated FAR customer
Subscription lines inherit their access control from the parent subscription's customer relationship.