Billing Cycles

Billing cycles control when invoices are generated and which service-history period is billed. In basic tSM billing, cycle execution is typically monthly, but configuration also supports quarterly and yearly frequencies.

This document provides business context first and then full field-level references for cycle entities.

---

1. Business Meaning

1.1 What a Billing Cycle Represents

BillingCycle is one concrete billing run period. It defines the billed interval (periodFrom, periodTo), execution dates, and current lifecycle status.

In practical operation, one billing cycle is used to:

• collect active services and relevant historical changes in the period,
• calculate monthly recurring charges and prorated values,
• produce billing documents linked to this cycle.

1.2 What a Billing Cycle Type Represents

BillingCycleType defines how cycles should be generated and scheduled (automatic/manual behavior, billing day, frequency). It is reusable configuration for many cycle instances.

1.3 Status Governance

Status governance is split into:

• a code-table entity BillingCycleStatus used for configuration and localization,
• a value enum BillingCycleStatus (ACTIVE, BILLED, TO_BE_BILLED) used by runtime logic.

1.4 Typical Cycle Flow

1. Configure cycle type (BillingCycleType) with frequency and billing day.
2. Open a cycle (BillingCycle) for a concrete period.
3. Compute charges for active services and history in the period.
4. Apply prorate when service activity covers only part of the cycle.
5. Generate billing documents and move cycle status to billed.

---

2. Entity Reference: BillingCycle (BillingCycle)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Cycle primary key.
code	String	Yes	No	Technical/business cycle code.
name	String	Yes	No	Display name.
validityFrom	Date	No	No	Deprecated validity start. Use periodFrom.
validityTo	Date	No	No	Deprecated validity end. Use periodTo.
description	String	No	No	Optional description.
localizationData	LocalizationData	No	No	Localization payload for label fields.
config	Map<String, Any?>	No	No	Additional configuration payload.
billingDate	Date	No	No	Billing execution date.
billingEnd	Date	No	No	Billing end date marker.
billingStart	Date	No	No	Billing start date marker.
dataTags	List<String>	No	No	Optional labels/tags.
billingCycleStatus	String	No	No	FK code to cycle status registry (BillingCycleStatus.code).
billingCycleType	String	Yes	No	FK code to cycle type registry (BillingCycleType.code).
periodFrom	Date	Yes	No	Start of relevant billed period.
periodTo	Date	Yes	No	End of relevant billed period.
chars	TsmChars	No	No	Dynamic cycle attributes.

2.1 Practical Notes

• Use periodFrom and periodTo as authoritative billing-period boundaries.
• validityFrom/validityTo remain only for compatibility with shared code-table interfaces.
• Status and period should always be evaluated together during cycle execution.

---

3. Entity Reference: BillingCycleType (BillingCycleType)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Cycle type primary key.
code	String	Yes	No	Technical cycle type code.
name	String	Yes	No	Display name.
description	String	No	No	Optional description.
validityFrom	Date	No	No	Validity start.
validityTo	Date	No	No	Validity end.
localizationData	LocalizationData	No	No	Localization payload.
dataTags	List<String>	No	No	Optional labels/tags.
config	Map<String, Any?>	No	No	Additional configuration payload.
automatically	Boolean	No	No	If true, customer billing is triggered automatically by schedule.
billingDate	Int	No	No	Ordinal day in selected frequency period (for example day in month).
managerReportDate	Int	No	No	Day in month when manager report should be generated.
billingFrequency	BillingFrequency	Yes	No	Billing recurrence frequency.
duration	Int	No	No	Optional cycle duration value.
mnemonicCode	String	No	No	Optional mnemonic code.

---

4. Entity Reference: BillingCycleStatus (BillingCycleStatus)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Status primary key.
code	String	Yes	No	Technical status code.
name	String	Yes	No	Display name.
validityFrom	Date	No	No	Validity start.
validityTo	Date	No	No	Validity end.
description	String	No	No	Optional status description.
localizationData	LocalizationData	No	No	Localization payload.
dataTags	List<String>	No	No	Optional labels/tags.
config	Map<String, Any?>	No	No	Additional configuration payload.

---

5. Enum Reference: BillingFrequency (BillingFrequency)

Value	Meaning
MONTHLY	Monthly cycle cadence (most common for basic recurring invoicing).
QUARTERLY	Quarterly cycle cadence.
YEARLY	Yearly cycle cadence.

6. Enum Reference: BillingCycleStatus (BillingCycleStatus)

Value	Meaning
ACTIVE	Cycle is open/active for processing.
BILLED	Cycle was billed and documents were generated.
TO_BE_BILLED	Cycle is prepared and waiting for billing execution.