Subscriptions module (subscriptions)

The subscriptions module in src/cluster_erp/modules/subscriptions/ records recurring business: plans that the company offers, subscriptions of customers to those plans, and subscriptions the company itself holds with vendors. It tracks billing periods, renewals, and expiry and emits lifecycle events; it produces no invoices. It is a business module, not the SaaS membership of a tenant, which is explained in multi-tenancy.

At a glance¶

What the module does¶

• A plan states what recurring product is sold, how often it bills, and at what price (src/cluster_erp/modules/subscriptions/plans/models.py:13-21).
• A sales subscription takes its terms from an active plan; a purchase subscription has its terms entered directly against a vendor (src/cluster_erp/modules/subscriptions/customer_subscriptions/services.py:129-206).
• Activation snapshots the plan's terms so that later plan changes do not rewrite history (src/cluster_erp/modules/subscriptions/customer_subscriptions/services.py:247-275).
• A daily sweep renews or expires subscriptions whose period has ended (src/cluster_erp/modules/subscriptions/customer_subscriptions/services.py:348-390, src/cluster_erp/server/app.py:504-546).

Sub-modules¶

Data model¶

Money values are Numeric columns and Decimal in schemas, and events carry amounts as strings (src/cluster_erp/modules/subscriptions/plans/models.py:43-47, src/cluster_erp/modules/subscriptions/plans/schemas.py:22-24, src/cluster_erp/modules/subscriptions/customer_subscriptions/services.py:415-444). See money and Decimal.

Screens and metadata¶

get_metadata declares a sidebar group Subscriptions (Turkish Abonelikler) with two list sections: Subscriptions for customer_subscription and Plans (Turkish Planlar) for subscription_plan (src/cluster_erp/modules/subscriptions/module.py:121-153). Billing cycle choices are Monthly, Quarterly, Semi-annual, and Annual (src/cluster_erp/modules/subscriptions/customer_subscriptions/metadata.py:40-45).

Status and actions¶

Plan statuses go draft to active to retired, with no way back (src/cluster_erp/modules/subscriptions/plans/services.py:101-117). Subscription statuses are draft, active, paused, cancelled, and expired (src/cluster_erp/modules/subscriptions/customer_subscriptions/models.py:97-100).

The state diagram shows a subscription's lifecycle.

stateDiagram-v2
    [*] --> draft: create
    draft --> active: activate
    active --> paused: pause
    paused --> active: resume
    active --> active: renew or sweep renewal
    active --> expired: sweep, end reached or renewal off
    draft --> cancelled: cancel
    active --> cancelled: cancel
    paused --> cancelled: cancel
    cancelled --> [*]
    expired --> [*]

In prose: a subscription is created as draft; activate starts the first period; pause and resume move between active and paused; renew or the sweep advances the period of an active subscription; the sweep expires an active subscription past its end date or whose period ended with renewal off; cancel ends any subscription that is not already cancelled or expired (src/cluster_erp/modules/subscriptions/customer_subscriptions/services.py:247-399). Labels come from the metadata label dictionaries.

Business rules¶

• A sales subscription needs a customer and an active plan; a purchase subscription needs a vendor, the full product triple, a price, a cycle, and a currency (src/cluster_erp/modules/subscriptions/customer_subscriptions/services.py:129-190).
• subscription_no and the plan code are yearly business keys from next_code (src/cluster_erp/modules/subscriptions/customer_subscriptions/services.py:112, src/cluster_erp/modules/subscriptions/plans/services.py:65).
• A period is the cycle length in months (1, 3, 6, or 12) times interval_count, anchored on the first period's day of month (src/cluster_erp/modules/subscriptions/customer_subscriptions/services.py:35-53, src/cluster_erp/modules/subscriptions/customer_subscriptions/services.py:328-339).
• The sweep catches up every period due and emits one renewal per period (src/cluster_erp/modules/subscriptions/customer_subscriptions/services.py:365-385).
• The amount in an event is unit price times quantity (src/cluster_erp/modules/subscriptions/customer_subscriptions/services.py:426-444).

Events and queries¶

A grep for the four event classes outside the module finds no subscriber at this commit.

Permissions¶

The lifecycle codes are seeded as extra codes (src/cluster_erp/server/app.py:837-847).

Privacy, retention, and history¶

The module stores party ids of customers and vendors but no personal fields of its own, and it has no privacy_handlers.py. Changes are captured by change history; see change history. Tenant-defined values in extra are filtered by permission on read (src/cluster_erp/modules/subscriptions/customer_subscriptions/routes.py:42-48).

Analytics facts¶

This module has no analytics_facts.py.

Settings and reference data¶

The module reads no dedicated settings. Currencies are three-letter codes validated by pattern in the plan schema (src/cluster_erp/modules/subscriptions/plans/schemas.py:23). The daily sweep runs per tenant database under a leader lock (src/cluster_erp/server/app.py:504-546).

Tests¶

Found by file name in tests/ and web-client/.

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• API reference for this module
• Identity, access, tenancy, privacy, and licensing
• Money and Decimal

Verified against commit 92f8051 on 2026-11-13.