Rhythm 2.0 Specifications

Appearance

DOM-MBR-MEM-005Billing Run

Markdown

DOM-MBR-MEM-005

Billing Run

Markdown
  • DocumentDraft
  • ImplementationPartially observed

Planning

Specified by
CON-MBR-MEM-005

Design

Owned by
SVC-MBR-MEM-billing

KindDomain objectProduct areaMembershipModuleMemberships, Applications and Membership BillingRevision1

Read atservices-membership 5994c270react-console baf6dae3

Billing Run ​

What It Models ​

A billing run is a reviewable batch of renewal work for one program and end-date range. It separates selection from execution so staff can inspect the proposed work before placing orders, requesting notices or dropping lapsed periods. Templates and recurring schedules reuse that configuration.

Identity and Attributes ​

The run copies configuration and stores the planning date, statistics and candidate actions. Each action preserves the term version that staff reviewed. Recurring configuration calculates selection dates from each local occurrence and can request automatic execution.

Relationships ​

Actions reference memberships and their candidate terms. Commerce owns resulting orders, and Platform owns requested communications. The run keeps references and outcomes for accountability.

Invariants ​

Uniqueness protects recurring occurrences and action keys. Version and status checks protect run changes, while stale-term checks protect execution. Notice and drop effects commit with their result; order placement crosses a separate transaction boundary and relies on the order key.

How It Is Stored and Shared ​

Billing owns templates, runs, actions, recurring configuration and execution records. Durable jobs process actions in slices. The Membership schedule dispatcher delivers recurring occurrences. These records declare no custom fields.

Open Design Questions ​

Commerce placement is a refusing stub, and notice purposes are not connected to sending. Organization recipients remain undecided. An execution job that never starts has no deployed reconciler to return the run to a usable state.

Relationships

ToCardinalityOwnershipCrosses a serviceOn archive or delete
DOM-MBR-MEM-002one-to-manyActions reference selected terms and preserve the reviewed version.no
DOM-MBR-MEM-001one-to-manyAction selection reads suspension, origin and member preferences from the referenced holding.no

Invariants

InvariantProtectsEnforced atProvenance
INV-DOM-MBR-MEM-005-01
Selection bounds and recurring offset bounds must be ordered.
databaseobserved
services-membership:modules/billing/db/billing-runs.table.ts:billing_runs_range_check; modules/billing/db/recurring-billing-runs.table.ts:recurring_billing_runs_offsets_check
INV-DOM-MBR-MEM-005-02
One recurring configuration cannot create two runs for the same local occurrence date.
databaseobserved
services-membership:modules/billing/db/billing-runs.table.ts:billing_runs_occurrence_uidx
INV-DOM-MBR-MEM-005-03
A run cannot contain duplicate actions for the same kind, reminder index and candidate term.
databaseobserved
services-membership:modules/billing/db/billing-run-actions.table.ts:billing_run_actions_key_uidx
INV-DOM-MBR-MEM-005-04
Planning, execution and cancellation require a current version and a permitted run state.
servicetest
services-membership:tests/acceptance/billing/MBR-ACC-0406.acceptance.ts#MBR-ACC-0406
INV-DOM-MBR-MEM-005-05
Only planned actions are attempted; local database effects settle with their action, while order placement settles afterward.
servicetest
services-membership:modules/billing/tests/integration/billing-runs.integration.spec.ts#refuses as stale an action whose term changed after planning
INV-DOM-MBR-MEM-005-06
A candidate whose term version differs from the plan becomes stale without performing the action.
servicetest
services-membership:modules/billing/tests/integration/billing-runs.integration.spec.ts#refuses as stale an action whose term changed after planning
INV-DOM-MBR-MEM-005-07
Order placement uses a stable action-based key so a cooperating Commerce port recognizes repeats.
serviceobserved
services-membership:modules/billing/services/execution/execute-action.ts:executeOrder
INV-DOM-MBR-MEM-005-08
A dropping template must reference a reason valid for term termination.
servicetest
services-membership:tests/acceptance/billing/MBR-ACC-0402.acceptance.ts#MBR-ACC-0402
INV-DOM-MBR-MEM-005-09
Concurrent recurring changes at the same version allow one winner and reject the stale writer.
servicetest
services-membership:modules/billing/tests/integration/recurring-billing-run-concurrency.integration.spec.ts#applies one of two changes made at the same version

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software