Api reference

components.premium.public.api ¶

PremiumAggregationService ¶

A service used to interact with subscription fees (AKA premiums in the context of insurance).

Fees are created to represent the consumption of Alan products. Many services throughout the stack need to consume fees to function: - invoicing aggregates fees into invoices - payroll reports the structure of the fees to give clarity to admins - data monitors general financial performance levels

This service is meant to become the one-stop-shop for all these consumers.

Additionally, the way we manage fees is evolving. Previously, each country & product had it's own engine for computing fees, and format to store them. We are moving toward a global solution: same engine and same format across all countries and products. However this is a still a work in progress, and this service also aims to protect consumers from having to deal with different formats. All functions are meant to function the same no matter which engine was used to compute the fees and how they were stored.

BELGIUM_PREMIUM_MIGRATION_WINDOW_END `class-attribute` `instance-attribute` ¶

BELGIUM_PREMIUM_MIGRATION_WINDOW_END = date(2026, 6, 30)

After this date, no premiums in Belgium were generated using the local engine. From this point, all premiums are stored in the global engine repository only.

BELGIUM_PREMIUM_MIGRATION_WINDOW_START `class-attribute` `instance-attribute` ¶

BELGIUM_PREMIUM_MIGRATION_WINDOW_START = date(2025, 12, 1)

The very first premium generated using the global engine in Belgium was generated for the month of December 2025. Before that date, all premiums in Belgium were generated using a local engine.

get_premium_entries_for_invoice `staticmethod` ¶

get_premium_entries_for_invoice(*, invoice_id)

Retrieve premium entries for a given invoice. If invoice has no components, then it retrieves legacy premium entries, and transforms them to PremiumEntry objects with components.

Parameters:

Name	Type	Description	Default
`invoice_id`	`UUID`	The ID of the invoice to retrieve premium entries for.	required

Returns:

Type	Description
`list[PremiumEntry]`	List of PremiumEntry objects for the invoice.

Source code in components/premium/public/api.py

@staticmethod
def get_premium_entries_for_invoice(
    *,
    invoice_id: UUID,
) -> list[PremiumEntry]:
    """
    Retrieve premium entries for a given invoice.
    If invoice has no components, then it retrieves legacy premium entries, and transforms them to PremiumEntry objects with components.

    Args:
        invoice_id: The ID of the invoice to retrieve premium entries for.

    Returns:
        List of PremiumEntry objects for the invoice.
    """
    dependencies = get_app_dependency()
    premium_repository = dependencies.get_premium_repository(session=None)

    premium_entries = premium_repository.get_premium_entries_for_invoice(invoice_id)

    if len(premium_entries) == 0:
        legacy_premium_repository = (
            dependencies.get_legacy_premium_entry_repository(session=None)
        )
        premium_entries = legacy_premium_repository.get_premium_entries_for_invoice(
            invoice_id
        )

    if len(premium_entries) > 0:
        return premium_entries

    raise ValueError("No premium entries found for invoice", invoice_id)

get_premiums_for_local_payroll `staticmethod` ¶

get_premiums_for_local_payroll(
    session,
    *,
    enrollment_ids,
    target_month,
    force_premium_source
)

Retrieve all premium entries to be included in a local payroll CSV where

payroll_csv_id IS NULL (global repo) or pay_csv_id IS NULL (legacy repo)
period_start <= target_month

In practice the aggregation service is supposed to shield consumers from the 'source' of premiums. However in practice this function does not require that complexity, considering this is a temporary bridge between local & global callers know what they need.

Parameters:

Name	Type	Description	Default
`session`	`Session`	SQLAlchemy session injected by @transactional decorator.	required
`enrollment_ids`	`list[UUID]`	UUIDs of enrollments to retrieve entries for.	required
`target_month`	`date`	Only entries with period_start <= last day of this month are returned.	required
`force_premium_source`	`Literal['legacy', 'global']`	Which SOT to use when fetching premiums	required

Source code in components/premium/public/api.py

@staticmethod
@transactional(
    propagation=Propagation.READ_ONLY, acceptable_replica_lag=timedelta(minutes=15)
)
def get_premiums_for_local_payroll(
    session: Session,
    *,
    enrollment_ids: list[UUID],
    target_month: date,
    force_premium_source: Literal["legacy", "global"],
) -> list[PremiumEntry]:
    """
    Retrieve all premium entries to be included in a local payroll CSV where:
        - payroll_csv_id IS NULL (global repo) or pay_csv_id IS NULL (legacy repo)
        - period_start <= target_month

    In practice the aggregation service is supposed to shield consumers from the
    'source' of premiums.
    However in practice this function does not require that complexity,
    considering this is a temporary bridge between local & global callers know what
    they need.

    Args:
        session: SQLAlchemy session injected by @transactional decorator.
        enrollment_ids: UUIDs of enrollments to retrieve entries for.
        target_month: Only entries with period_start <= last day of this month are returned.
        force_premium_source: Which SOT to use when fetching premiums
    """
    dependencies = get_app_dependency()

    match force_premium_source:
        case "legacy":
            legacy_repository = dependencies.get_legacy_premium_entry_repository(
                session
            )
            return legacy_repository.get_entries_for_local_payroll(
                enrollment_ids, target_month
            )
        case "global":
            repository = dependencies.get_premium_repository(session)

            return repository.get_entries_for_local_payroll(
                enrollment_ids, target_month
            )

get_premiums_for_payroll `staticmethod` ¶

get_premiums_for_payroll(
    session, *, enrollment_ids, cutoff_date
)

Retrieve all entries where

at least some part of the total amount is meant to be billed to the company.
the premiums's period_start is after cutoff_date
the premium's created_at is after cutoff_date

To shield callers from the details of the progress into the various premium migrations, this function is able to read and reconcile from multiple sources.

Considering this function is meant for the usage of payroll batch jobs, it has been designed with a certain amount of care when it comes to performance: - the read happens on a read-replica - we guarantee a set number of queries no matter how many enrollment IDs are passed (no N+1) - the process of reading 1,000 entries consumes around 16 MB of memory at peak - once all transient objects have been released by the garbage collector and only the dataclass instances remain, 1,000 entries weigh around 5 MB - you can find methodology and instructions to reproduce the measurements in the component's README

Parameters:

Name	Type	Description	Default
`session`	`Session`	SQLAlchemy session injected by @transactional decorator.	required
`enrollment_ids`	`list[int \| UUID]`	IDs of enrollments to retrieve entries for.	required
`cutoff_date`	`date`	Only entries with period_start or created_at after this date are returned.	required

Returns:

Type	Description
`list[PremiumEntry]`	List of complete PremiumEntry objects.

Source code in components/premium/public/api.py

@staticmethod
@transactional(
    propagation=Propagation.READ_ONLY, acceptable_replica_lag=timedelta(minutes=15)
)
def get_premiums_for_payroll(
    session: Session,
    *,
    enrollment_ids: list[int | UUID],
    cutoff_date: date,
) -> list[PremiumEntry]:
    """
    Retrieve all entries where:
        - at least some part of the total amount is meant to be billed to the company.
        - the premiums's period_start is after cutoff_date
        - the premium's created_at is after cutoff_date

    To shield callers from the details of the progress into the various premium
    migrations, this function is able to read and reconcile from multiple sources.

    Considering this function is meant for the usage of payroll batch jobs, it has
    been designed with a certain amount of care when it comes to performance:
        - the read happens on a read-replica
        - we guarantee a set number of queries no matter how many enrollment IDs are
          passed (no N+1)
        - the process of reading 1,000 entries consumes around 16 MB of memory
          at peak
        - once all transient objects have been released by the garbage collector
          and only the dataclass instances remain, 1,000 entries weigh around 5 MB
        - you can find methodology and instructions to reproduce the measurements
          in the component's README

    Args:
        session: SQLAlchemy session injected by @transactional decorator.
        enrollment_ids: IDs of enrollments to retrieve entries for.
        cutoff_date: Only entries with period_start or created_at after this date
            are returned.

    Returns:
        List of complete PremiumEntry objects.
    """
    dependencies = get_app_dependency()
    repository = dependencies.get_premium_repository(session)
    legacy_repository = dependencies.get_legacy_premium_entry_repository(session)

    match get_current_app_name():
        case AppName.ALAN_BE:
            migration_window_end_date = (
                PremiumAggregationService.BELGIUM_PREMIUM_MIGRATION_WINDOW_END
            )
        case app_name:
            raise NotImplementedError(
                f"get_premiums_for_payroll is not implemented for {app_name}"
            )

    if cutoff_date >= migration_window_end_date:
        return repository.get_entries_for_payroll(enrollment_ids, cutoff_date)

    new_entries = repository.get_entries_for_payroll(enrollment_ids, cutoff_date)
    legacy_entries = legacy_repository.get_entries_for_payroll(
        enrollment_ids, cutoff_date
    )

    new_entry_periods = {(e.enrollment_id, e.period_start) for e in new_entries}
    deduplicated_legacy = [
        e
        for e in legacy_entries
        if (e.enrollment_id, e.period_start) not in new_entry_periods
    ]
    return new_entries + deduplicated_legacy

get_uninvoiced_premiums `staticmethod` ¶

get_uninvoiced_premiums(
    *, policy: Policy, up_to: date
) -> list[PremiumEntry]

get_uninvoiced_premiums(
    *, contract: Contract, up_to: date
) -> list[PremiumEntry]

get_uninvoiced_premiums(
    *, policy=None, contract=None, up_to
)

Retrieve premium entries with uninvoiced components, checking specifically if the company or primary part is invoiced.

Returns complete premium entries where at least one component has not been invoiced yet. The debtor is inferred from the contract type: - Policy: primary policy holder - Contract → company

Parameters:

Name	Type	Description	Default
`policy`	`Policy \| None`	Policy to retrieve premiums for (mutually exclusive with contract).	`None`
`contract`	`Contract \| None`	Contract to retrieve premiums for (mutually exclusive with policy).	`None`
`up_to`	`date`	Only returns entries where period_end <= up_to.	required

Returns:

Type	Description
`list[PremiumEntry]`	List of complete PremiumEntry objects with uninvoiced components.

Source code in components/premium/public/api.py

@staticmethod
def get_uninvoiced_premiums(
    *,
    policy: Policy | None = None,
    contract: Contract | None = None,
    up_to: date,
) -> list[PremiumEntry]:
    """
    Retrieve premium entries with uninvoiced components, checking specifically if
    the company or primary part is invoiced.

    Returns complete premium entries where at least one component has not been
    invoiced yet. The debtor is inferred from the contract type:
      - Policy: primary policy holder
      - Contract → company

    Args:
        policy: Policy to retrieve premiums for (mutually exclusive with contract).
        contract: Contract to retrieve premiums for (mutually exclusive with policy).
        up_to: Only returns entries where period_end <= up_to.

    Returns:
        List of complete PremiumEntry objects with uninvoiced components.
    """
    repository = get_app_dependency().get_premium_repository(session=None)

    if policy:
        debtor = InsuranceBilledEntity.primary
        enrollment_ids = [enrollment.id for enrollment in policy.enrollments]
    elif contract:
        debtor = InsuranceBilledEntity.company
        enrollment_ids = [
            enrollment.id
            for policy in contract.policies
            for enrollment in policy.enrollments
        ]
    else:
        raise ValueError("Either policy or contract must be provided")

    return repository.get_all_uninvoiced_entries_up_to(
        enrollment_ids=enrollment_ids,
        debtor=debtor,
        up_to=up_to,
    )

mark_entries_for_payroll `staticmethod` ¶

mark_entries_for_payroll(
    session, premium_entry_ids, payroll_csv_id
)

Mark premium entries as included in a payroll CSV.

Tries the global repository first. If no entries are found there, falls back to the legacy repository.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Database session.	required
`premium_entry_ids`	`list[UUID]`	IDs of the premium entries to mark.	required
`payroll_csv_id`	`UUID`	The payroll CSV ID to set on matching entries.	required

Source code in components/premium/public/api.py

@staticmethod
@transactional(force_manage=True)
def mark_entries_for_payroll(
    session: Session,
    premium_entry_ids: list[UUID],
    payroll_csv_id: UUID,
) -> None:
    """
    Mark premium entries as included in a payroll CSV.

    Tries the global repository first. If no entries are found there,
    falls back to the legacy repository.

    Args:
        session: Database session.
        premium_entry_ids: IDs of the premium entries to mark.
        payroll_csv_id: The payroll CSV ID to set on matching entries.
    """
    dependencies = get_app_dependency()
    repository = dependencies.get_premium_repository(session)
    legacy_repository = dependencies.get_legacy_premium_entry_repository(session)

    updated_count = repository.mark_entries_for_payroll(
        premium_entry_ids, payroll_csv_id
    )
    if updated_count == 0:
        legacy_repository.mark_entries_for_payroll(
            premium_entry_ids, payroll_csv_id
        )

mark_premiums_as_invoiced `staticmethod` ¶

mark_premiums_as_invoiced(
    session, premium_entries, *, invoice_id, debtor
)

Mark premium entries as invoiced by setting invoice_id on matching components.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Database session.	required
`premium_entries`	`list[PremiumEntry]`	List of premium entries to mark as invoiced.	required
`invoice_id`	`UUID`	The invoice ID to set on matching components.	required
`debtor`	`InsuranceBilledEntity`	The billed entity whose components should be marked as invoiced.	required

Source code in components/premium/public/api.py

@staticmethod
@transactional
def mark_premiums_as_invoiced(
    session: Session,
    premium_entries: list[PremiumEntry],
    *,
    invoice_id: UUID,
    debtor: InsuranceBilledEntity,
) -> None:
    """
    Mark premium entries as invoiced by setting invoice_id on matching components.

    Args:
        session: Database session.
        premium_entries: List of premium entries to mark as invoiced.
        invoice_id: The invoice ID to set on matching components.
        debtor: The billed entity whose components should be marked as invoiced.
    """
    repository = get_app_dependency().get_premium_repository(session)

    updated_entries = [
        entry.with_components_marked_as_invoiced(invoice_id, debtor=debtor)
        for entry in premium_entries
    ]

    repository.update(updated_entries)

PremiumComputationService ¶

Compute premiums.

Not responsible for storing the computed premiums

compute_insurance_premiums `staticmethod` ¶

compute_insurance_premiums(
    session,
    *,
    policy,
    contract,
    start_month,
    end_month,
    engine_parameters=None
)

Compute how much money is owed to Alan and persist the results.

Parameters:

Name	Type	Description	Default
`session`	`Session`	SQLAlchemy session injected by @transactional decorator	required
`policy`	`Policy`	The insurance policy containing enrollments	required
`contract`	`Contract`	The contract defining pricing terms	required
`start_month`	`Month`	First month to calculate premiums for	required
`end_month`	`Month`	Last month to include in premium calculations	required
`engine_parameters`	`EngineParameters \| None`	Optional engine configuration. If not provided, uses defaults for current application	`None`

Returns:

Type	Description
`list[PremiumEntry]`	All fresh entries returned by the computation.

Source code in components/premium/public/api.py

@staticmethod
@transactional()
def compute_insurance_premiums(
    session: Session,
    *,
    policy: Policy,
    contract: Contract,
    start_month: Month,
    end_month: Month,
    engine_parameters: EngineParameters | None = None,
) -> list[PremiumEntry]:
    """
    Compute how much money is owed to Alan and persist the results.

    Args:
        session: SQLAlchemy session injected by @transactional decorator
        policy: The insurance policy containing enrollments
        contract: The contract defining pricing terms
        start_month: First month to calculate premiums for
        end_month: Last month to include in premium calculations
        engine_parameters: Optional engine configuration. If not provided, uses
            defaults for current application

    Returns:
        All fresh entries returned by the computation.
    """
    repository = get_app_dependency().get_premium_repository(session)
    engine_parameters = engine_parameters or EngineParameters.default(
        app_name=get_current_app_name()
    )

    affiliation_builder = AffiliationTimelineBuilder(
        policy=policy,
        contract=contract,
        engine_parameters=engine_parameters,
    )

    affiliation_timeline = affiliation_builder.compute_affiliation_timeline(
        start_date=start_month.first_day,
        end_date=end_month.last_day,
    )

    cost_timeline = map_timeline(
        affiliation_timeline,
        lambda period: CostPeriod(
            validity_period=period.validity_period,
            start_reason=period.start_reason,
            cost=CorePriceAdapter.from_core_price_cost(
                PricingService.get_breakdown(
                    pricing_source=PolicyPricingSource(policy.id),
                    on_date=period.validity_period.start_date,
                    member_specs=[
                        CorePriceAdapter.to_core_price_beneficiary_spec(spec)
                        for spec in period.beneficiary_specs
                    ],
                    rounding_strategy=engine_parameters.rounding_strategy,
                )
            ),
        ),
    )

    all_new_entries = compute_subscription_fees(
        cost_timeline=cost_timeline,
        periodicity=Periodicity.monthly,
        start=start_month,
        end=end_month,
        engine_parameters=engine_parameters,
    )

    enrollment_ids = [enrollment.id for enrollment in policy.enrollments]
    existing_premiums = repository.get_latest_entries(
        enrollment_ids=enrollment_ids,
        lower_bound=start_month,
        upper_bound=end_month,
    )

    result = reconcile_premium_entries(
        new_premiums=all_new_entries,
        existing_premiums=existing_premiums,
    )

    repository.update(result["existing_entries_to_update"])
    repository.insert(
        result["cancelling_entries_to_insert"] + result["new_entries_to_insert"]
    )

    return all_new_entries

components.premium.public.commands ¶

components.premium.public.cost_types ¶

Insurance cost types for the premium component.

This module contains premium's own definitions of insurance domain types, decoupling it from price_provider component implementations. Changes to price_provider's internal pricing logic should not require changes to premium's domain model.

Currency and rounding strategy are intentionally NOT duplicated - import them from components.core_price.public.primitives.

InsuranceBeneficiary ¶

Bases: AlanBaseEnum

Represents the different types of insurance beneficiaries.

children `class-attribute` `instance-attribute` ¶

children = 'children'

from_enrollment_type `classmethod` ¶

from_enrollment_type(enrollment_type)

Convert EnrollmentType to InsuranceBeneficiary.

Source code in components/premium/public/cost_types.py

@classmethod
def from_enrollment_type(
    cls, enrollment_type: EnrollmentType
) -> "InsuranceBeneficiary":
    """Convert EnrollmentType to InsuranceBeneficiary."""
    if enrollment_type == EnrollmentType.primary:
        return cls.primary
    elif enrollment_type == EnrollmentType.partner:
        return cls.partner
    elif enrollment_type == EnrollmentType.child:
        return cls.children
    else:
        raise ValueError(f"Unknown enrollment type: {enrollment_type}")

partner `class-attribute` `instance-attribute` ¶

partner = 'partner'

primary `class-attribute` `instance-attribute` ¶

primary = 'primary'

to_enrollment_type ¶

to_enrollment_type()

Convert InsuranceBeneficiary to EnrollmentType.

Source code in components/premium/public/cost_types.py

def to_enrollment_type(self) -> EnrollmentType:
    """Convert InsuranceBeneficiary to EnrollmentType."""
    if self == InsuranceBeneficiary.primary:
        return EnrollmentType.primary
    elif self == InsuranceBeneficiary.partner:
        return EnrollmentType.partner
    elif self == InsuranceBeneficiary.children:
        return EnrollmentType.child
    else:
        raise ValueError(f"Unknown beneficiary type: {self}")

InsuranceBilledEntity ¶

Bases: AlanBaseEnum

Represents an entity paying for an insurance service.

company `class-attribute` `instance-attribute` ¶

company = 'company'

partner `class-attribute` `instance-attribute` ¶

partner = 'partner'

primary `class-attribute` `instance-attribute` ¶

primary = 'primary'

InsuranceCollectionMethod ¶

Bases: AlanBaseEnum

Methods for collecting an employee's participation.

direct_billing `class-attribute` `instance-attribute` ¶

direct_billing = 'direct_billing'

The amount is paid directly by the employee or their partner, using the payment method of their choice.

flexben_fund `class-attribute` `instance-attribute` ¶

flexben_fund = 'flexben_fund'

The amount is paid from the employee's flexben fund.

payroll `class-attribute` `instance-attribute` ¶

payroll = 'payroll'

The amount is paid by the company but automatically deducted from the employee's payslip.

InsuranceContribution ¶

Bases: AlanBaseEnum

Represents how an amount is used, what the money is going towards.

cost `class-attribute` `instance-attribute` ¶

cost = 'cost'

discount `class-attribute` `instance-attribute` ¶

discount = 'discount'

membership_fee `class-attribute` `instance-attribute` ¶

membership_fee = 'membership_fee'

social_fund `class-attribute` `instance-attribute` ¶

social_fund = 'social_fund'

taxes `class-attribute` `instance-attribute` ¶

taxes = 'taxes'

InsuranceCost `dataclass` ¶

InsuranceCost(*, cost_components)

Represents the entire cost of an insurance service.

No safeties on cost components

There are no checks verifying there are no duplicates in components. The caller is responsible for ensuring the components represent a valid cost breakdown.

Source code in components/premium/public/cost_types.py

def __init__(self, *, cost_components: list[InsuranceCostComponent]):
    if len(cost_components) == 0:
        raise ValueError("No components to build a cost out of.")

    self.cost_components = cost_components
    self.currency = cost_components[0].currency

    # Compute some intermediary values frequently used by consumers, in O(n) time
    untaxed_amount_billed_to_primary = 0
    untaxed_amount_billed_to_company = 0

    taxes_billed_to_company = 0
    taxes_billed_to_primary = 0

    for component in cost_components:
        if component.currency != self.currency:
            raise ValueError("Cannot mix different currencies.")

        match component.billed_entity:
            case InsuranceBilledEntity.company:
                if component.contribution_type == InsuranceContribution.taxes:
                    taxes_billed_to_company += component.amount
                else:
                    untaxed_amount_billed_to_company += component.amount
            case InsuranceBilledEntity.primary:
                if component.contribution_type == InsuranceContribution.taxes:
                    taxes_billed_to_primary += component.amount
                else:
                    untaxed_amount_billed_to_primary += component.amount
            case billed_entity:
                raise NotImplementedError(
                    f"Unimplement billed entity: {billed_entity}"
                )

    taxed_amount_billed_to_primary = (
        untaxed_amount_billed_to_primary + taxes_billed_to_primary
    )
    taxed_amount_billed_to_company = (
        untaxed_amount_billed_to_company + taxes_billed_to_company
    )

    self.taxed_amount_billed_to_primary = taxed_amount_billed_to_primary
    self.untaxed_amount_billed_to_primary = untaxed_amount_billed_to_primary
    self.untaxed_amount_billed_to_company = untaxed_amount_billed_to_company
    self.taxed_amount_billed_to_company = taxed_amount_billed_to_company

    # Once initialised, the dataclass is frozen.
    # Enforced via custom __setattr__ implementation.
    self._initialized = True

setattr ¶

__setattr__(name, value)

Setting attributes once the dataclass is initialized is forbidden. Reproducing the behavior of frozen=True.

Source code in components/premium/public/cost_types.py

def __setattr__(self, name: str, value: object) -> None:
    """
    Setting attributes once the dataclass is initialized is forbidden.
    Reproducing the behavior of frozen=True.
    """
    if hasattr(self, "_initialized") and self._initialized:
        raise AttributeError(
            f"Cannot modify {name} after initialization. InsuranceCost is immutable."
        )
    super().__setattr__(name, value)

cost_components `instance-attribute` ¶

cost_components = cost_components

currency `instance-attribute` ¶

currency = currency

from_components `staticmethod` ¶

from_components(cost_components)

Construct an InsuranceCost from several cost components.

Raises:

Type	Description
`NotImplementedError`	if the billed entity is not implemented yet
`ValueError`	if the currency used by all the components is not the same

Source code in components/premium/public/cost_types.py

@staticmethod
def from_components(
    cost_components: list[InsuranceCostComponent],
) -> "InsuranceCost":
    """
    Construct an InsuranceCost from several cost components.

    Raises:
        NotImplementedError: if the billed entity is not implemented yet
        ValueError: if the currency used by all the components is not the same
    """
    return InsuranceCost(cost_components=cost_components)

merge `staticmethod` ¶

merge(insurance_costs)

Merge several costs into the same cost objects.

When we evaluate the costs of coverage modules individually, merging them is useful to get the total aggregated costs.

Source code in components/premium/public/cost_types.py

@staticmethod
def merge(
    insurance_costs: list["InsuranceCost"],
) -> "InsuranceCost":
    """
    Merge several costs into the same cost objects.

    When we evaluate the costs of coverage modules individually, merging them is
    useful to get the total aggregated costs.
    """
    if len(insurance_costs) == 1:
        return insurance_costs[0]

    all_components: list[InsuranceCostComponent] = []
    for cost in insurance_costs:
        all_components.extend(cost.cost_components)
    return InsuranceCost.from_components(all_components)

taxed_amount_billed_to_company `instance-attribute` ¶

taxed_amount_billed_to_company = (
    taxed_amount_billed_to_company
)

taxed_amount_billed_to_primary `instance-attribute` ¶

taxed_amount_billed_to_primary = (
    taxed_amount_billed_to_primary
)

untaxed_amount_billed_to_company `instance-attribute` ¶

untaxed_amount_billed_to_company = (
    untaxed_amount_billed_to_company
)

untaxed_amount_billed_to_primary `instance-attribute` ¶

untaxed_amount_billed_to_primary = (
    untaxed_amount_billed_to_primary
)

InsuranceCostComponent `dataclass` ¶

InsuranceCostComponent(
    *,
    service_type,
    contribution_type,
    beneficiary_type,
    billed_entity,
    collection_method=None,
    enrollment_id=None,
    currency,
    amount,
    periodicity="monthly"
)

Represents part of a cost of insurance service.

__post_init__ ¶

__post_init__()

Validate that collection method is set when billed entity is not company.

Source code in components/premium/public/cost_types.py

def __post_init__(self) -> None:
    """Validate that collection method is set when billed entity is not company."""
    if (
        self.billed_entity != InsuranceBilledEntity.company
        and self.collection_method is None
    ):
        raise ValueError(
            f"Collection method must be set when billed entity is {self.billed_entity}"
        )

amount `instance-attribute` ¶

amount

The amount for an entire period of service.

Can be negative, for example if the amount corresponds to a discount. Must be expressed in the minor unit of the chosen currency.

beneficiary_type `instance-attribute` ¶

beneficiary_type

Who's coverage does this cost correspond to ?

billed_entity `instance-attribute` ¶

billed_entity

Who is responsible for paying this cost ?

collection_method `class-attribute` `instance-attribute` ¶

collection_method = None

If an employee is responsible for paying this cost, how is the payment collected ?

compare_component_lists `staticmethod` ¶

compare_component_lists(left, right)

Compare two lists of insurance cost components for equality.

Parameters:

Name	Type	Description	Default
`left`	`list[InsuranceCostComponent]`	First list of components to compare	required
`right`	`list[InsuranceCostComponent]`	Second list of components to compare	required

Returns:

Type	Description
`bool`	True if both lists contain the same components in any order, False otherwise

Source code in components/premium/public/cost_types.py

@staticmethod
def compare_component_lists(
    left: list["InsuranceCostComponent"], right: list["InsuranceCostComponent"]
) -> bool:
    """
    Compare two lists of insurance cost components for equality.

    Args:
        left: First list of components to compare
        right: Second list of components to compare

    Returns:
        True if both lists contain the same components in any order, False otherwise
    """
    return set(left) == set(right)

contribution_type `instance-attribute` ¶

contribution_type

What part of the service is paid for by this cost?

currency `instance-attribute` ¶

currency

enrollment_id `class-attribute` `instance-attribute` ¶

enrollment_id = None

An optional enrollment ID, in case the component corresponds to an enrolled member. It would typically be set when computing the prices for an existing policy. It would be None when a member projects the cost of adding their partner to their policy.

group_by_beneficiary_id `staticmethod` ¶

group_by_beneficiary_id(components)

Groups insurance cost components by enrollment ID.

Parameters:

Name	Type	Description	Default
`components`	`list[InsuranceCostComponent]`	List of InsuranceCostComponent to group	required

Returns:

Type	Description
`dict[int \| UUID, list[InsuranceCostComponent]]`	Dictionary mapping enrollment ID (int or UUID) to list of components

Raises:

Type	Description
`ValueError`	If any component does not have an enrollment ID

Source code in components/premium/public/cost_types.py

@staticmethod
def group_by_beneficiary_id(
    components: list["InsuranceCostComponent"],
) -> dict[int | UUID, list["InsuranceCostComponent"]]:
    """
    Groups insurance cost components by enrollment ID.

    Args:
        components: List of InsuranceCostComponent to group

    Returns:
        Dictionary mapping enrollment ID (int or UUID) to list of components

    Raises:
        ValueError: If any component does not have an enrollment ID
    """
    grouped: dict[int | UUID, list[InsuranceCostComponent]] = {}

    for component in components:
        if component.enrollment_id is None:
            raise ValueError("All components must have an enrollment ID")

        enrollment_id = component.enrollment_id
        if enrollment_id not in grouped:
            grouped[enrollment_id] = []
        grouped[enrollment_id].append(component)

    return grouped

periodicity `class-attribute` `instance-attribute` ¶

periodicity = 'monthly'

service_type `instance-attribute` ¶

service_type

What insurance service does this cost correspond to ?

InsuranceService ¶

Bases: AlanBaseEnum

Represents an insurance coverage module.

base `class-attribute` `instance-attribute` ¶

base = 'base'

extended `class-attribute` `instance-attribute` ¶

extended = 'extended'

Base + option rolled into the same coverage module.

hospitalization `class-attribute` `instance-attribute` ¶

hospitalization = 'hospitalization'

Neutral label for single-coverage plans (no base/extended distinction).

option `class-attribute` `instance-attribute` ¶

option = 'option'

components.premium.public.dependencies ¶

COMPONENT_NAME `module-attribute` ¶

COMPONENT_NAME = 'premium'

Canonical name of the premium component.

PremiumDependency ¶

Bases: ABC

Represents all the dependency required by components/premium to function as expected.

get_flexben_timeline_for_all_enrollments_of_the_policy `abstractmethod` ¶

get_flexben_timeline_for_all_enrollments_of_the_policy(
    policy_id, start_date=None, end_date=None
)

For each enrollment in the policy, return a list of periods where a flexben choice is enabled.

Considering flexben is a feature local to Belgium, we expect components/be to be the only caller to actually inject this dependency. Other components are expected to inject a function returning an empty dict.

Example

{ enrollment_id_1: [ ValidityPeriod(date(2024, 1, 1), date(2024, 6, 30)), ], enrollment_id_2: [ ValidityPeriod(date(2024, 3, 1), date(2024, 12, 31)), ], }

Source code in components/premium/public/dependencies.py

@abstractmethod
def get_flexben_timeline_for_all_enrollments_of_the_policy(
    self,
    policy_id: int | UUID,
    start_date: date | None = None,
    end_date: date | None = None,
) -> "dict[int | UUID, list[ValidityPeriod]]":
    """
    For each enrollment in the policy, return a list of periods where a flexben
    choice is enabled.

    Considering flexben is a feature local to Belgium, we expect `components/be` to
    be the only caller to actually inject this dependency.
    Other components are expected to inject a function returning an empty dict.

    Example:
        {
            enrollment_id_1: [
                ValidityPeriod(date(2024, 1, 1), date(2024, 6, 30)),
            ],
            enrollment_id_2: [
                ValidityPeriod(date(2024, 3, 1), date(2024, 12, 31)),
            ],
        }
    """
    ...

get_legacy_premium_entry_repository `abstractmethod` ¶

get_legacy_premium_entry_repository(session)

Instantiate layer to retrieve premium entries based on legacy ones

Source code in components/premium/public/dependencies.py

@abstractmethod
def get_legacy_premium_entry_repository(
    self, session: Session | None
) -> PremiumEntryRepository:
    """
    Instantiate layer to retrieve premium entries based on legacy ones
    """
    ...

get_premium_repository `abstractmethod` ¶

get_premium_repository(session)

Instantiate a persistence layer for premium repository

Source code in components/premium/public/dependencies.py

@abstractmethod
def get_premium_repository(self, session: Session | None) -> PremiumEntryRepository:
    """
    Instantiate a persistence layer for premium repository
    """
    ...

get_app_dependency ¶

get_app_dependency()

Function used to fetch the dependencies from the flask app.

Source code in components/premium/public/dependencies.py

def get_app_dependency() -> PremiumDependency:
    """Function used to fetch the dependencies from the flask app."""
    from flask import current_app

    return cast("CustomFlask", current_app).get_component_dependency(COMPONENT_NAME)  # type: ignore[no-any-return]

set_app_dependency ¶

set_app_dependency(dependency)

Function used to actually inject the dependency class in the component.

Source code in components/premium/public/dependencies.py

def set_app_dependency(dependency: PremiumDependency) -> None:
    """Function used to actually inject the dependency class in the component."""
    from flask import current_app

    cast("CustomFlask", current_app).add_component_dependency(
        COMPONENT_NAME, dependency
    )

components.premium.public.entities ¶

AgeStrategy ¶

Bases: AlanBaseEnum

Strategy for handling age calculation in insurance premium calculations.

The effective birthday or age we use for pricing a beneficiary may differ from their actual birthday or age.

KEEP_EXACT_BIRTHDAY `class-attribute` `instance-attribute` ¶

KEEP_EXACT_BIRTHDAY = 'exact_date'

Use the exact birthday for age calculation.

Example: If a member turns 23 on March 15, 2023, their age changes exactly on March 15, 2023.

MOVE_BIRTHDAY_TO_FIRST_DAY_OF_MONTH `class-attribute` `instance-attribute` ¶

MOVE_BIRTHDAY_TO_FIRST_DAY_OF_MONTH = (
    "move_to_first_day_of_month"
)

Move birthday to the first day of the birth month for age calculation.

Example: If a member turns 23 on March 15, 2023, they will be priced as 23 years old starting March 1, 2023 for the entire month.

MOVE_BIRTHDAY_TO_JAN_OF_NEXT_YEAR `class-attribute` `instance-attribute` ¶

MOVE_BIRTHDAY_TO_JAN_OF_NEXT_YEAR = 'jan_of_next_year'

Move birthday to January 1st of the year following the birth year.

Example: If a member turns 23 on March 15, 2023, they will be priced as 22 years old for the entirety of 2023, and 23 years old starting January 1, 2024.

Contract ¶

Bases: Protocol

get_simple_subscription_version_timeline ¶

get_simple_subscription_version_timeline()

Source code in components/premium/internal/domain/insurance_entities.py

def get_simple_subscription_version_timeline(
    self,
) -> Timeline[SimpleSubscriptionVersion]: ...

is_cancelled `instance-attribute` ¶

is_cancelled

policies `instance-attribute` ¶

policies

CostPeriod `dataclass` ¶

CostPeriod(*, start_reason, cost)

Bases: GenericPeriodWithStartReason

Represents a timeline period with computed premium cost.

Final output of the premium calculation pipeline, containing the actual cost for the stable period. Each period guarantees the cost remains constant throughout its validity period.

Attributes:

Name	Type	Description
`cost`	`Cost`	The computed insurance cost for this period, calculated based on the stable beneficiary composition and contract terms.

cost `instance-attribute` ¶

cost

EngineParameters `dataclass` ¶

EngineParameters(
    *,
    age_strategy,
    rounding_strategy,
    prorata_strategy,
    default_child_age,
    default_adult_age
)

Parameters dictating how the engine behaves and which rules it follows.

Example

which effective birth date to use
which prorata formula to use
which rounding strategy to use

age_strategy `instance-attribute` ¶

age_strategy

default `staticmethod` ¶

default(app_name)

Get default engine parameters for a given application. Application is used as a proxy for country.

Parameters:

Name	Type	Description	Default
`name`		The application name to get default parameters for	required

Raises:

Type	Description
`ValueError`	If the application is not yet supported

Source code in components/premium/internal/domain/engine_parameters.py

@staticmethod
def default(app_name: AppName) -> "EngineParameters":
    """
    Get default engine parameters for a given application.
    Application is used as a proxy for country.

    Args:
        name: The application name to get default parameters for

    Raises:
        ValueError: If the application is not yet supported
    """
    match app_name:
        case AppName.ALAN_BE:
            return EngineParameters(
                age_strategy=AgeStrategy.MOVE_BIRTHDAY_TO_FIRST_DAY_OF_MONTH,
                rounding_strategy=RoundingStrategy.BANKERS,
                prorata_strategy=ProrataStrategy.THIRTY_DAY_PRORATA_WITH_LARGEST_REMAINDER_DISTRIBUTION_ACROSS_FEE_COMPONENTS,
                default_child_age=17,
                default_adult_age=25,
            )
        case AppName.ALAN_FR:
            return EngineParameters(
                age_strategy=AgeStrategy.MOVE_BIRTHDAY_TO_JAN_OF_NEXT_YEAR,
                rounding_strategy=RoundingStrategy.BANKERS,
                prorata_strategy=ProrataStrategy.THIRTY_DAY_PRORATA_WITH_LARGEST_REMAINDER_DISTRIBUTION_ACROSS_FEE_COMPONENTS,
                default_child_age=17,
                default_adult_age=25,
            )
        case _:
            raise ValueError(f"Unsupported app_name: {app_name}")

default_adult_age `instance-attribute` ¶

default_adult_age

Optional strategy for normalizing ages into specific buckets for pricing. When None, ages are used directly from beneficiary birthdates or defaults. When specified, the strategy determines how to group beneficiaries by age.

default_child_age `instance-attribute` ¶

default_child_age

prorata_strategy `instance-attribute` ¶

prorata_strategy

rounding_strategy `instance-attribute` ¶

rounding_strategy

FeeComponent `dataclass` ¶

FeeComponent(
    *,
    id=uuid4(),
    num_days,
    invoice_id,
    amount_before_prorata
)

Bases: CostComponent

A fee component represents one part of a fee that we intend to bill to a customer.

eq ¶

__eq__(other)

Source code in components/premium/internal/domain/fee.py

def __eq__(self, other: object) -> bool:
    if not isinstance(other, FeeComponent):
        return False

    return (
        self.num_days == other.num_days
        and self.amount == other.amount
        and self.amount_before_prorata == other.amount_before_prorata
        and self.currency == other.currency
        and self.beneficiary_type == other.beneficiary_type
        and self.service_type == other.service_type
        and self.contribution_type == other.contribution_type
        and self.billed_entity == other.billed_entity
        and self.collection_method == other.collection_method
        and self.enrollment_id == other.enrollment_id
    )

hash ¶

__hash__()

Source code in components/premium/internal/domain/fee.py

def __hash__(self) -> int:
    return hash(
        (
            self.num_days,
            self.amount,
            self.amount_before_prorata,
            self.currency.alphabetic_code,
            self.beneficiary_type,
            self.service_type,
            self.contribution_type,
            self.billed_entity,
            self.collection_method,
            str(self.enrollment_id) if self.enrollment_id else None,
        )
    )

amount_before_prorata `instance-attribute` ¶

amount_before_prorata

Amount for full period coverage without prorata applied. Expressed in the minor unit of the currency. This is the full monthly amount that would be charged for complete period coverage.

as_tuple ¶

as_tuple()

Return (billed_entity, contribution_type, amount)

Source code in components/premium/internal/domain/fee.py

def as_tuple(
    self,
) -> tuple["InsuranceBilledEntity", "InsuranceContribution", int]:
    """Return (billed_entity, contribution_type, amount)"""

    return (self.billed_entity, self.contribution_type, self.amount)

id `class-attribute` `instance-attribute` ¶

id = field(default_factory=uuid4)

Unique identifier of the entry

inverted ¶

inverted()

Returns a new FeeComponent offsetting the current one.

Source code in components/premium/internal/domain/fee.py

def inverted(self) -> "FeeComponent":
    """
    Returns a new FeeComponent offsetting the current one.
    """
    return FeeComponent(
        num_days=-self.num_days,
        amount=-self.amount,
        amount_before_prorata=-self.amount_before_prorata,
        currency=self.currency,
        beneficiary_type=self.beneficiary_type,
        service_type=self.service_type,
        contribution_type=self.contribution_type,
        billed_entity=self.billed_entity,
        collection_method=self.collection_method,
        enrollment_id=self.enrollment_id,
        invoice_id=None,
    )

invoice_id `instance-attribute` ¶

invoice_id

If the component is included in an invoice, it is represented here.

num_days `instance-attribute` ¶

num_days

Number of days this fee covers within the billing period.

LegacyBelgianNormalization `dataclass` ¶

LegacyBelgianNormalization()

Groups beneficiaries into specific age buckets: - Children are treated as adults if they are 25 or above - Young adults (18-25) are priced as 25 or above if they are the primary policy holder or their partner - No birthdate available: default to age 25 - Anyone not falling in one of the buckets above: use their actual age

CHILD_AGE_LIMIT_YEARS `class-attribute` `instance-attribute` ¶

CHILD_AGE_LIMIT_YEARS = 25

normalize_age ¶

normalize_age(
    effective_birthdate, enrollment_type, reference_date
)

Source code in components/premium/internal/domain/age_normalization.py

def normalize_age(
    self,
    effective_birthdate: date | None,
    enrollment_type: EnrollmentType,
    reference_date: date,
) -> int:
    if not effective_birthdate:
        return self.CHILD_AGE_LIMIT_YEARS

    age = age_on(effective_birthdate, reference_date)

    if enrollment_type != EnrollmentType.child and age < self.CHILD_AGE_LIMIT_YEARS:
        return self.CHILD_AGE_LIMIT_YEARS

    if enrollment_type == EnrollmentType.child and age < self.CHILD_AGE_LIMIT_YEARS:
        return 17

    return age

Policy ¶

Bases: Historizable

enrollments `instance-attribute` ¶

enrollments

id `instance-attribute` ¶

id

PremiumEntry `dataclass` ¶

PremiumEntry(
    *,
    id=uuid4(),
    enrollment_id,
    components,
    period_start,
    period_end,
    version=1,
    cancelled_by_entry_id=None,
    cancelled_entry_id=None,
    payroll_csv_id=None
)

A subscription fee specific to insurance subscriptions.

eq ¶

__eq__(other)

Source code in components/premium/internal/domain/fee.py

def __eq__(self, other: object) -> bool:
    if not isinstance(other, PremiumEntry):
        return False

    return (
        self.enrollment_id == other.enrollment_id
        and self.period_start == other.period_start
        and self.period_end == other.period_end
        and set(self.components) == set(other.components)
    )

hash ¶

__hash__()

Source code in components/premium/internal/domain/fee.py

def __hash__(self) -> int:
    return hash(
        (
            str(self.enrollment_id),
            self.period_start,
            self.period_end,
            frozenset(self.components),
        )
    )

beneficiary_type `property` ¶

beneficiary_type

cancelled ¶

cancelled()

Returns two new entries: one marking this entry as cancelled, and one offsetting it.

Returns:

Type	Description
`tuple[PremiumEntry, PremiumEntry \| None]`	tuple[PremiumEntry, PremiumEntry]: - First entry: Same as self but marked as cancelled - Second entry: New entry to offset self.

Source code in components/premium/internal/domain/fee.py

def cancelled(self) -> tuple["PremiumEntry", "PremiumEntry | None"]:
    """
    Returns two new entries: one marking this entry as cancelled, and one offsetting it.

    Returns:
        tuple[PremiumEntry, PremiumEntry]:
            - First entry: Same as self but marked as cancelled
            - Second entry: New entry to offset self.
    """

    # If B cancels A and we cancel B, it's equivalent to undoing the cancelation of
    # A
    # Therefore, canceling entries should never get canceled.
    if self.cancelled_entry_id:
        return self, None

    if self.cancelled_by_entry_id:
        return self, None

    cancelling_entry_id = uuid4()

    cancelled_entry = PremiumEntry(
        id=self.id,
        enrollment_id=self.enrollment_id,
        components=self.components,
        period_start=self.period_start,
        period_end=self.period_end,
        version=self.version,
        cancelled_entry_id=self.cancelled_entry_id,
        cancelled_by_entry_id=cancelling_entry_id,
        payroll_csv_id=self.payroll_csv_id,
    )

    offsetting_entry = PremiumEntry(
        id=cancelling_entry_id,
        enrollment_id=self.enrollment_id,
        components=[component.inverted() for component in self.components],
        period_start=self.period_start,
        period_end=self.period_end,
        version=self.version + 1,
        cancelled_by_entry_id=None,
        cancelled_entry_id=self.id,
        payroll_csv_id=self.payroll_csv_id,
    )

    return cancelled_entry, offsetting_entry

cancelled_by_entry_id `class-attribute` `instance-attribute` ¶

cancelled_by_entry_id = field(default=None)

cancelled_entry_id `class-attribute` `instance-attribute` ¶

cancelled_entry_id = field(default=None)

components `instance-attribute` ¶

components

components_billed_to_debtor ¶

components_billed_to_debtor(debtor)

Returns components that are actually billed to the specified debtor.

This method accounts for collection methods: - If debtor is company: includes company components AND primary components with (payroll or flexben_fund) - If debtor is primary: only includes primary components with direct_billing

Source code in components/premium/internal/domain/fee.py

def components_billed_to_debtor(
    self, debtor: "InsuranceBilledEntity"
) -> list[FeeComponent]:
    """
    Returns components that are actually billed to the specified debtor.

    This method accounts for collection methods:
    - If debtor is company: includes company components AND primary components with (payroll or flexben_fund)
    - If debtor is primary: only includes primary components with direct_billing
    """
    return [
        c for c in self.components if self._is_component_billed_to_debtor(c, debtor)
    ]

components_for_debtor ¶

components_for_debtor(debtor)

The debtor is not necessarily the entity being billed

If a component's debtor is the primary but the collection method is payroll, the company gets billed.

If your purpose is to list components that should be invoiced to a given debtor, use components_billed_to_debtor().

Source code in components/premium/internal/domain/fee.py

def components_for_debtor(
    self, debtor: "InsuranceBilledEntity"
) -> list[FeeComponent]:
    """
    !!! warning "The debtor is not necessarily the entity being billed"

        If a component's debtor is the primary but the collection method is payroll,
        the company gets billed.

        If your purpose is to list components that should be invoiced to a given debtor,
        use `components_billed_to_debtor()`.
    """
    return [c for c in self.components if c.billed_entity == debtor]

currency `property` ¶

currency

enrollment_id `instance-attribute` ¶

enrollment_id

id `class-attribute` `instance-attribute` ¶

id = field(default_factory=uuid4)

num_days `property` ¶

num_days

payroll_csv_id `class-attribute` `instance-attribute` ¶

payroll_csv_id = field(default=None)

Belgium & Spain's local payroll systems requires to keep track of which premiums are included in which file.

In order to maintain compatibility between Belgium payroll and Global premiums we need to maintain this property. However it's not required by the Global payroll system, therefore this property is temporary and will be dropped as soon as global payroll is online.

period_end `instance-attribute` ¶

period_end

period_start `instance-attribute` ¶

period_start

pretax_amount_billed_to_debtor ¶

pretax_amount_billed_to_debtor(debtor)

Returns the total pretax amount (membership fees + costs) billed to the specified debtor.

This includes components with contribution_type of: - InsuranceContribution.membership_fee: Base membership fees - InsuranceContribution.cost: Insurance coverage costs

This method accounts for collection methods: - If debtor is company: includes company components AND primary components with (payroll or flexben_fund) - If debtor is primary: only includes primary components with direct_billing

Parameters:

Name	Type	Description	Default
`debtor`	`InsuranceBilledEntity`	The entity to which costs are billed	required

Returns:

Type	Description
`int`	Total pretax amount in minor currency units

Source code in components/premium/internal/domain/fee.py

def pretax_amount_billed_to_debtor(self, debtor: "InsuranceBilledEntity") -> int:
    """
    Returns the total pretax amount (membership fees + costs) billed to the specified debtor.

    This includes components with contribution_type of:
    - InsuranceContribution.membership_fee: Base membership fees
    - InsuranceContribution.cost: Insurance coverage costs

    This method accounts for collection methods:
    - If debtor is company: includes company components AND primary components with (payroll or flexben_fund)
    - If debtor is primary: only includes primary components with direct_billing

    Args:
        debtor: The entity to which costs are billed

    Returns:
        Total pretax amount in minor currency units
    """
    return sum(
        c.amount
        for c in self.components
        if self._is_component_billed_to_debtor(c, debtor)
        and c.contribution_type
        in [
            InsuranceContribution.membership_fee,
            InsuranceContribution.cost,
        ]
    )

prorata_ratio ¶

prorata_ratio()

Returns the prorata ratio for this premium entry.

The ratio is calculated as: - 1.0 (or -1.0 for negative days) if the premium covers the full month - num_days / 30 otherwise (using 30-day convention, rounded to 2 decimals)

Uses arithmetic rounding (ROUND_HALF_UP) for consistency with invoicing display.

Returns:

Type	Description
`float`	Prorata ratio as a float. Positive for regular premiums, negative for credits/reversals.

Source code in components/premium/internal/domain/fee.py

def prorata_ratio(self) -> float:
    """
    Returns the prorata ratio for this premium entry.

    The ratio is calculated as:
    - 1.0 (or -1.0 for negative days) if the premium covers the full month
    - num_days / 30 otherwise (using 30-day convention, rounded to 2 decimals)

    Uses arithmetic rounding (ROUND_HALF_UP) for consistency with invoicing display.

    Returns:
        Prorata ratio as a float. Positive for regular premiums, negative for credits/reversals.
    """
    from shared.helpers.math import arithmetic_round

    # TODO: @florian.gagnadre 2026-01-21
    # Temporary solution for occupational health subscription fees.
    # We should probably find a better way to manga pro-rata for different periods.
    if self.num_days in [365, 366]:
        return 1.0

    if self.num_days in [-365, -366]:
        return -1.0

    if abs(self.num_days) == Month(self.period_start).n_days:
        return 1.0 if self.num_days > 0 else -1.0
    else:
        return arithmetic_round(self.num_days / 30, ndigits=2)

service_type `property` ¶

service_type

taxes_billed_to_debtor ¶

taxes_billed_to_debtor(debtor)

Returns the total tax amount billed to the specified debtor.

This includes components with contribution_type of: - InsuranceContribution.taxes: Tax components

This method accounts for collection methods: - If debtor is company: includes company components AND primary components with (payroll or flexben_fund) - If debtor is primary: only includes primary components with direct_billing

Parameters:

Name	Type	Description	Default
`debtor`	`InsuranceBilledEntity`	The entity to which taxes are billed	required

Returns:

Type	Description
`int`	Total tax amount in minor currency units

Source code in components/premium/internal/domain/fee.py

def taxes_billed_to_debtor(self, debtor: "InsuranceBilledEntity") -> int:
    """
    Returns the total tax amount billed to the specified debtor.

    This includes components with contribution_type of:
    - InsuranceContribution.taxes: Tax components

    This method accounts for collection methods:
    - If debtor is company: includes company components AND primary components with (payroll or flexben_fund)
    - If debtor is primary: only includes primary components with direct_billing

    Args:
        debtor: The entity to which taxes are billed

    Returns:
        Total tax amount in minor currency units
    """
    return sum(
        c.amount
        for c in self.components
        if self._is_component_billed_to_debtor(c, debtor)
        and c.contribution_type == InsuranceContribution.taxes
    )

total_amount ¶

total_amount()

Source code in components/premium/internal/domain/fee.py

def total_amount(self) -> int:
    return sum(c.amount for c in self.components)

total_amount_billed_to_debtor ¶

total_amount_billed_to_debtor(debtor)

Returns the total amount for components actually billed to the specified debtor.

This method accounts for collection methods: - If debtor is company: includes company components AND primary components with (payroll or flexben_fund) - If debtor is primary: only includes primary components with direct_billing

Source code in components/premium/internal/domain/fee.py

def total_amount_billed_to_debtor(self, debtor: "InsuranceBilledEntity") -> int:
    """
    Returns the total amount for components actually billed to the specified debtor.

    This method accounts for collection methods:
    - If debtor is company: includes company components AND primary components with (payroll or flexben_fund)
    - If debtor is primary: only includes primary components with direct_billing
    """
    return sum(
        c.amount
        for c in self.components
        if self._is_component_billed_to_debtor(c, debtor)
    )

total_amount_for_debtor ¶

total_amount_for_debtor(debtor)

The debtor is not necessarily the entity being billed

If a component's debtor is the primary but the collection method is payroll, the company gets billed.

If your purpose is to compute the total amount that should be invoiced to a given debtor, use total_amount_billed_to_debtor().

Source code in components/premium/internal/domain/fee.py

def total_amount_for_debtor(self, debtor: "InsuranceBilledEntity") -> int:
    """
    !!! warning "The debtor is not necessarily the entity being billed"

        If a component's debtor is the primary but the collection method is payroll,
        the company gets billed.

        If your purpose is to compute the total amount that should be invoiced to a given debtor,
        use `total_amount_billed_to_debtor()`.
    """
    return sum(c.amount for c in self.components if c.billed_entity == debtor)

total_billed_to_debtor_without_prorata ¶

total_billed_to_debtor_without_prorata(debtor)

Returns the total amount before prorata for components actually billed to the specified debtor.

This method accounts for collection methods: - If debtor is company: includes company components AND primary components with (payroll or flexben_fund) - If debtor is primary: only includes primary components with direct_billing

Source code in components/premium/internal/domain/fee.py

def total_billed_to_debtor_without_prorata(
    self, debtor: "InsuranceBilledEntity"
) -> int:
    """
    Returns the total amount before prorata for components actually billed to the specified debtor.

    This method accounts for collection methods:
    - If debtor is company: includes company components AND primary components with (payroll or flexben_fund)
    - If debtor is primary: only includes primary components with direct_billing
    """
    return sum(
        c.amount_before_prorata
        for c in self.components
        if self._is_component_billed_to_debtor(c, debtor)
    )

total_for_debtor_without_prorata ¶

total_for_debtor_without_prorata(debtor)

The debtor is not necessarily the entity being billed

If a component's debtor is the primary but the collection method is payroll, the company gets billed.

If your purpose is to compute the total amount without prorata that should be invoiced to a given debtor, use total_billed_to_debtor_without_prorata().

Source code in components/premium/internal/domain/fee.py

def total_for_debtor_without_prorata(self, debtor: "InsuranceBilledEntity") -> int:
    """
    !!! warning "The debtor is not necessarily the entity being billed"

        If a component's debtor is the primary but the collection method is payroll,
        the company gets billed.

        If your purpose is to compute the total amount without prorata that should be invoiced to a given debtor,
        use `total_billed_to_debtor_without_prorata()`.
    """
    return sum(
        c.amount_before_prorata
        for c in self.components
        if c.billed_entity == debtor
    )

version `class-attribute` `instance-attribute` ¶

version = field(default=1)

with_components_marked_as_invoiced ¶

with_components_marked_as_invoiced(invoice_id, *, debtor)

Returns a new PremiumEntry with components for the specified debtor marked as invoiced.

Parameters:

Name	Type	Description	Default
`invoice_id`	`UUID`	The invoice ID to set on matching components.	required
`debtor`	`InsuranceBilledEntity`	The billed entity whose components should be marked as invoiced.	required

Returns:

Type	Description
`PremiumEntry`	New PremiumEntry with updated components.

Source code in components/premium/internal/domain/fee.py

def with_components_marked_as_invoiced(
    self, invoice_id: UUID, *, debtor: "InsuranceBilledEntity"
) -> "PremiumEntry":
    """
    Returns a new PremiumEntry with components for the specified debtor marked as invoiced.

    Args:
        invoice_id: The invoice ID to set on matching components.
        debtor: The billed entity whose components should be marked as invoiced.

    Returns:
        New PremiumEntry with updated components.
    """
    updated_components = [
        FeeComponent(
            id=component.id,
            num_days=component.num_days,
            amount=component.amount,
            amount_before_prorata=component.amount_before_prorata,
            currency=component.currency,
            beneficiary_type=component.beneficiary_type,
            service_type=component.service_type,
            contribution_type=component.contribution_type,
            billed_entity=component.billed_entity,
            collection_method=component.collection_method,
            enrollment_id=component.enrollment_id,
            invoice_id=invoice_id
            if self._is_component_billed_to_debtor(component, debtor)
            else component.invoice_id,
        )
        for component in self.components
    ]

    return PremiumEntry(
        id=self.id,
        enrollment_id=self.enrollment_id,
        components=updated_components,
        period_start=self.period_start,
        period_end=self.period_end,
        version=self.version,
        cancelled_by_entry_id=self.cancelled_by_entry_id,
        cancelled_entry_id=self.cancelled_entry_id,
        payroll_csv_id=self.payroll_csv_id,
    )

with_version ¶

with_version(version)

Returns a new PremiumEntry with a different version.

Source code in components/premium/internal/domain/fee.py

def with_version(self, version: int) -> "PremiumEntry":
    """Returns a new PremiumEntry with a different version."""
    return PremiumEntry(
        id=self.id,
        enrollment_id=self.enrollment_id,
        components=self.components,
        period_start=self.period_start,
        period_end=self.period_end,
        version=version,
        cancelled_by_entry_id=self.cancelled_by_entry_id,
        cancelled_entry_id=self.cancelled_entry_id,
        payroll_csv_id=self.payroll_csv_id,
    )

PremiumEntryRepository ¶

Bases: Protocol

Repository protocol for persisting and retrieving premium entries.

get_all_entries ¶

get_all_entries(enrollment_ids, period_start, period_end)

Retrieve all premium entries for specified enrollments with an optional period.

Returns all stored premium entries including both cancelled and active entries.

Parameters:

Name	Type	Description	Default
`enrollment_ids`	`list[int \| UUID]`	IDs (int or UUID) of enrollments to retrieve entries for. Some implementations may only support UUID IDs and will raise an error if int IDs are provided.	required
`period_start`	`Month \| date \| None`	Optional lower bound for the entry period. If provided, only returns entries where entry.period_start == period_start. If Month is passed, use the first day of the month. If None, there is no filter on the start date of the period.	required
`period_end`	`Month \| date \| None`	Optional upper bound for the entry period. If provided, only returns entries where entry.period_end == period_end. If Month is passed, use the last day of the month. If None, there is no filter on the end date of the period.	required

Returns:

Type	Description
`list[PremiumEntry]`	List of PremiumEntry objects matching the filtering criteria.
`list[PremiumEntry]`	If both date parameters are None, returns all entries for the enrollments.

Source code in components/premium/internal/domain/repository.py

def get_all_entries(
    self,
    enrollment_ids: list[int | UUID],
    period_start: Month | date | None,
    period_end: Month | date | None,
) -> list[PremiumEntry]:
    """
    Retrieve all premium entries for specified enrollments with an optional period.

    Returns all stored premium entries including both cancelled and active entries.

    Args:
        enrollment_ids: IDs (int or UUID) of enrollments to retrieve entries for.
            Some implementations may only support UUID IDs and will raise an error
            if int IDs are provided.
        period_start: Optional lower bound for the entry period.
            If provided, only returns entries where entry.period_start == period_start.
            If Month is passed, use the first day of the month.
            If None, there is no filter on the start date of the period.
        period_end: Optional upper bound for the entry period.
            If provided, only returns entries where entry.period_end == period_end.
            If Month is passed, use the last day of the month.
            If None, there is no filter on the end date of the period.

    Returns:
        List of PremiumEntry objects matching the filtering criteria.
        If both date parameters are None, returns all entries for the enrollments.
    """
    ...

get_all_uninvoiced_entries_up_to ¶

get_all_uninvoiced_entries_up_to(
    enrollment_ids, debtor, up_to
)

Retrieve premium entries that have uninvoiced components for a specific debtor.

An entry is included if it has at least one component where the debtor has not been invoiced (invoice_id IS NULL). The returned entries are complete - they contain all components regardless of their invoice status or debtor.

Parameters:

Name	Type	Description	Default
`enrollment_ids`	`list[int \| UUID]`	IDs (int or UUID) of enrollments to retrieve entries for. Some implementations may only support UUID IDs and will raise an error if int IDs are provided.	required
`debtor`	`InsuranceBilledEntity`	The billed entity (primary, company, etc.) to check for uninvoiced components.	required
`up_to`	`date`	Only returns entries where period_end <= up_to.	required

Returns:

Type	Description
`list[PremiumEntry]`	List of complete PremiumEntry objects.

Source code in components/premium/internal/domain/repository.py

def get_all_uninvoiced_entries_up_to(
    self,
    enrollment_ids: list[int | UUID],
    debtor: "InsuranceBilledEntity",
    up_to: date,
) -> list[PremiumEntry]:
    """
    Retrieve premium entries that have uninvoiced components for a specific debtor.

    An entry is included if it has at least one component where the debtor has not
    been invoiced (invoice_id IS NULL). The returned entries are complete - they
    contain all components regardless of their invoice status or debtor.

    Args:
        enrollment_ids: IDs (int or UUID) of enrollments to retrieve entries for.
            Some implementations may only support UUID IDs and will raise an error
            if int IDs are provided.
        debtor: The billed entity (primary, company, etc.) to check for uninvoiced components.
        up_to: Only returns entries where period_end <= up_to.

    Returns:
        List of complete PremiumEntry objects.
    """
    ...

get_entries_for_local_payroll ¶

get_entries_for_local_payroll(enrollment_ids, target_month)

Retrieve all entries where payroll_csv_id IS NULL and period_start <= target_month.

Parameters:

Name	Type	Description	Default
`enrollment_ids`	`list[UUID]`	IDs of enrollments to retrieve entries for.	required
`target_month`	`date`	Only entries with period_start on or before this date are returned.	required

Source code in components/premium/internal/domain/repository.py

def get_entries_for_local_payroll(
    self,
    enrollment_ids: list[UUID],
    target_month: date,
) -> list[PremiumEntry]:
    """
    Retrieve all entries where payroll_csv_id IS NULL and period_start <= target_month.

    Args:
        enrollment_ids: IDs of enrollments to retrieve entries for.
        target_month: Only entries with period_start on or before this date are returned.
    """
    ...

get_entries_for_payroll ¶

get_entries_for_payroll(enrollment_ids, cutoff_date)

Retrieve all entries where

at least one component is billed to the company
the premiums's period_start is after cutoff_date
the premium's created_at is after cutoff_date

Parameters:

Name	Type	Description	Default
`enrollment_ids`	`list[int \| UUID]`	IDs (int or UUID) of enrollments to retrieve entries for.	required
`cutoff_date`	`date`	Only entries with period_start or created_at after this date are returned.	required

Source code in components/premium/internal/domain/repository.py

def get_entries_for_payroll(
    self,
    enrollment_ids: list[int | UUID],
    cutoff_date: date,
) -> list[PremiumEntry]:
    """
    Retrieve all entries where:
        - at least one component is billed to the company
        - the premiums's period_start is after cutoff_date
        - the premium's created_at is after cutoff_date

    Args:
        enrollment_ids: IDs (int or UUID) of enrollments to retrieve entries for.
        cutoff_date: Only entries with period_start or created_at after this date
            are returned.
    """
    ...

get_latest_entries ¶

get_latest_entries(
    enrollment_ids, lower_bound, upper_bound
)

Retrieve the latest premium entries for specified enrollments for all periods contained within lower_bound and upper_bound.

Lower bound and upper bound may cover more than one period

The caller is free to pass any range they would like. We return one premium entry, per enrollment, per period in the range.

Parameters:

Name	Type	Description	Default
`enrollment_ids`	`list[int \| UUID]`	IDs (int or UUID) of enrollments to retrieve entries for. Some implementations may only support UUID IDs and will raise an error if int IDs are provided.	required
`lower_bound`	`Month \| date`	Range start. If Month is passed, use the first day of the month.	required
`upper_bound`	`Month \| date`	Range end. If Month is passed, use the last day of the month.	required

Returns:

Type	Description
`list[PremiumEntry]`	One premium entry per enrollment per period in the range.
`list[PremiumEntry]`	For each period, the premium returned is the latest as defined by the
`list[PremiumEntry]`	version.

Examples:

>>> # Single month range returns 1 entry per enrollment
>>> repo.get_latest_entries(
...     enrollment_ids=[uuid1, uuid2],
...     lower_bound=Month(2024, 1),
...     upper_bound=Month(2024, 1)
... )
[PremiumEntry(...period_start=2024-01-01...)]

>>> # Three month range returns 3 entries per enrollment
>>> repo.get_latest_entries(
...     enrollment_ids=[uuid1],
...     lower_bound=Month(2024, 1),
...     upper_bound=Month(2024, 3)
... )
[
    PremiumEntry(...period_start=2024-01-01...),
    PremiumEntry(...period_start=2024-02-01...),
    PremiumEntry(...period_start=2024-03-01...)
]

Source code in components/premium/internal/domain/repository.py

def get_latest_entries(
    self,
    enrollment_ids: list[int | UUID],
    lower_bound: Month | date,
    upper_bound: Month | date,
) -> list[PremiumEntry]:
    """
    Retrieve the latest premium entries for specified enrollments for all periods
    contained within lower_bound and upper_bound.

    !!! warning "Lower bound and upper bound may cover more than one period"

        The caller is free to pass any range they would like.
        We return one premium entry, per enrollment, per period in the range.

    Args:
        enrollment_ids: IDs (int or UUID) of enrollments to retrieve entries for.
            Some implementations may only support UUID IDs and will raise an error
            if int IDs are provided.
        lower_bound: Range start. If Month is passed, use the first day of the month.
        upper_bound: Range end. If Month is passed, use the last day of the month.

    Returns:
        One premium entry per enrollment per period in the range.
        For each period, the premium returned is the latest as defined by the
        version.

    Examples:
        >>> # Single month range returns 1 entry per enrollment
        >>> repo.get_latest_entries(
        ...     enrollment_ids=[uuid1, uuid2],
        ...     lower_bound=Month(2024, 1),
        ...     upper_bound=Month(2024, 1)
        ... )
        [PremiumEntry(...period_start=2024-01-01...)]

        >>> # Three month range returns 3 entries per enrollment
        >>> repo.get_latest_entries(
        ...     enrollment_ids=[uuid1],
        ...     lower_bound=Month(2024, 1),
        ...     upper_bound=Month(2024, 3)
        ... )
        [
            PremiumEntry(...period_start=2024-01-01...),
            PremiumEntry(...period_start=2024-02-01...),
            PremiumEntry(...period_start=2024-03-01...)
        ]
    """
    ...

get_premium_entries_for_invoice ¶

get_premium_entries_for_invoice(invoice_id)

Retrieve premium entries for a specific invoice. If invoice has no components, then it returns an empty list.

Parameters:

Name	Type	Description	Default
`invoice_id`	`HybridId`	The ID of the invoice to retrieve premium entries for.	required

Returns:

Type	Description
`list[PremiumEntry]`	List of PremiumEntry objects for the invoice.

Source code in components/premium/internal/domain/repository.py

def get_premium_entries_for_invoice(
    self, invoice_id: HybridId
) -> list[PremiumEntry]:
    """
    Retrieve premium entries for a specific invoice.
    If invoice has no components, then it returns an empty list.

    Args:
        invoice_id: The ID of the invoice to retrieve premium entries for.

    Returns:
        List of PremiumEntry objects for the invoice.
    """
    ...

insert ¶

insert(entries)

Insert new premium entries into the database.

Parameters:

Name	Type	Description	Default
`entries`	`list[PremiumEntry]`	List of PremiumEntry objects to insert. Each entry's components will be added to the database.	required

Source code in components/premium/internal/domain/repository.py

def insert(self, entries: list[PremiumEntry]) -> None:
    """
    Insert new premium entries into the database.

    Args:
        entries: List of PremiumEntry objects to insert.
                 Each entry's components will be added to the database.
    """
    ...

mark_entries_for_payroll ¶

mark_entries_for_payroll(premium_entry_ids, payroll_csv_id)

Mark premium entries as included in a payroll CSV by setting payroll_csv_id.

Parameters:

Name	Type	Description	Default
`premium_entry_ids`	`list[UUID]`	IDs of the premium entries to mark.	required
`payroll_csv_id`	`UUID`	The payroll CSV ID to set on matching entries.	required

Returns:

Type	Description
`int`	Number of entries updated.

Source code in components/premium/internal/domain/repository.py

def mark_entries_for_payroll(
    self,
    premium_entry_ids: list[UUID],
    payroll_csv_id: UUID,
) -> int:
    """
    Mark premium entries as included in a payroll CSV by setting payroll_csv_id.

    Args:
        premium_entry_ids: IDs of the premium entries to mark.
        payroll_csv_id: The payroll CSV ID to set on matching entries.

    Returns:
        Number of entries updated.
    """
    ...

session `instance-attribute` ¶

session

update ¶

update(entries)

Update existing premium entries in the database.

Parameters:

Name	Type	Description	Default
`entries`	`list[PremiumEntry]`	List of PremiumEntry objects to update. Each entry's components will be merged into the database.	required

Source code in components/premium/internal/domain/repository.py

def update(self, entries: list[PremiumEntry]) -> None:
    """
    Update existing premium entries in the database.

    Args:
        entries: List of PremiumEntry objects to update.
                 Each entry's components will be merged into the database.
    """
    ...

ProrataStrategy ¶

Bases: AlanBaseEnum

Strategy for applying prorata to cost components.

When multiple cost components need prorating (e.g., base cost, membership fee, taxes), different strategies can be used that may produce slightly different results due to rounding.

THIRTY_DAY_PRORATA `class-attribute` `instance-attribute` ¶

THIRTY_DAY_PRORATA = '30_day_prorata'

If the service covers the whole month, bill the full amount for 1 month. A month is a full month if the number of days covered equals the number of days in the month. If the service does not cover the whole month, prorate on the base of 30 days.

Formula: monthly_price * days_covered / 30

This prorata is applied to all the components of the subscription fee and may carry rounding errors, meaning the total of components may exceed the initial total.

THIRTY_DAY_PRORATA_WITH_LARGEST_REMAINDER_DISTRIBUTION_ACROSS_FEE_COMPONENTS `class-attribute` `instance-attribute` ¶

THIRTY_DAY_PRORATA_WITH_LARGEST_REMAINDER_DISTRIBUTION_ACROSS_FEE_COMPONENTS = "30_day_prorata_with_largest_remainder_distribution_across_fee_components"

Similar to THIRTY_DAY_PRORATA except rounding errors are avoided by using the largest remainder algorithm to distribute the last few cents across the component.

There is a risk of losing accuracy, for example attributing more to the membership fee than we should. But we have the guarantee the total of the components will never exceed the initial total and the inaccuracies should never exceed 1 cent.

SubscriptionPeriod `dataclass` ¶

SubscriptionPeriod(*, fees)

Bases: GenericPeriod

fees `instance-attribute` ¶

fees

components.premium.public.models ¶

premium_component ¶

PremiumComponentModel ¶

Bases: BaseModel

A model describing how to store global premium entries...

Each country is responsible for reimplementing their own model, inheriting from this one.

abstract `class-attribute` `instance-attribute` ¶

__abstract__ = True

__table_args__ `class-attribute` `instance-attribute` ¶

__table_args__ = (
    UniqueConstraint(
        "enrollment_id",
        "premium_entry_id",
        "coverage_type",
        "beneficiary_type",
        "debtor_type",
        "period_start",
        "period_end",
        "contribution_type",
        "version",
        name="one_component_across_all_dimensions_per_version",
    ),
    Index(
        "ix_enrollment_id_version",
        "enrollment_id",
        "version",
    ),
    Index(
        "ix_period_start_end", "period_start", "period_end"
    ),
)

amount `class-attribute` `instance-attribute` ¶

amount = mapped_column(Integer, nullable=False)

Amount for num_days of coverage from period_start to period_end. Expressed in the minor unit of the currency.

amount_before_prorata `class-attribute` `instance-attribute` ¶

amount_before_prorata = mapped_column(
    Integer, nullable=False
)

Amount for full coverage from period_start to period_end. Expressed in the minor unit of the currency. This is the amount that would be billed if we decided not to apply prorata.

beneficiary_type `class-attribute` `instance-attribute` ¶

beneficiary_type = mapped_column(
    Enum(InsuranceBeneficiary), nullable=False
)

cancelled_by_entry_id `class-attribute` `instance-attribute` ¶

cancelled_by_entry_id = mapped_column(
    UUID(as_uuid=True), nullable=True, index=True
)

cancelled_entry_id `class-attribute` `instance-attribute` ¶

cancelled_entry_id = mapped_column(
    UUID(as_uuid=True), nullable=True, index=True
)

collection_method `class-attribute` `instance-attribute` ¶

collection_method = mapped_column(
    Enum(InsuranceCollectionMethod, nullable=True)
)

contribution_type `class-attribute` `instance-attribute` ¶

contribution_type = mapped_column(
    Enum(InsuranceContribution), nullable=False
)

coverage_type `class-attribute` `instance-attribute` ¶

coverage_type = mapped_column(
    Enum(InsuranceService), nullable=False
)

currency `class-attribute` `instance-attribute` ¶

currency = mapped_column(String, nullable=False)

ISO4217 compliant alpha code of the currency.

debtor_type `class-attribute` `instance-attribute` ¶

debtor_type = mapped_column(
    Enum(InsuranceBilledEntity), nullable=False
)

enrollment_id `class-attribute` `instance-attribute` ¶

enrollment_id = mapped_column(
    UUID(as_uuid=True), nullable=False
)

invoice_id `class-attribute` `instance-attribute` ¶

invoice_id = mapped_column(nullable=True, index=True)

num_days `class-attribute` `instance-attribute` ¶

num_days = mapped_column(Integer, nullable=False)

Number of days this fee covers within the billing period.

payroll_csv_id `class-attribute` `instance-attribute` ¶

payroll_csv_id = mapped_column(
    UUID(as_uuid=True), nullable=True
)

Belgium & Spain's local payroll systems requires to keep track of which premiums are included in which file.

In order to maintain compatibility between Belgium payroll and Global premiums we need to maintain this property. However it's not required by the Global payroll system, therefore this property is temporary and will be dropped as soon as global payroll is online.

period_end `class-attribute` `instance-attribute` ¶

period_end = mapped_column(Date, nullable=False)

period_start `class-attribute` `instance-attribute` ¶

period_start = mapped_column(Date, nullable=False)

premium_entry_id `class-attribute` `instance-attribute` ¶

premium_entry_id = mapped_column(
    UUID(as_uuid=True), nullable=False
)

version `class-attribute` `instance-attribute` ¶

version = mapped_column(Integer, nullable=False)

Api reference

components.premium.public.api ¶

PremiumAggregationService ¶

BELGIUM_PREMIUM_MIGRATION_WINDOW_END class-attribute instance-attribute ¶

BELGIUM_PREMIUM_MIGRATION_WINDOW_START class-attribute instance-attribute ¶

get_premium_entries_for_invoice staticmethod ¶

get_premiums_for_local_payroll staticmethod ¶

get_premiums_for_payroll staticmethod ¶

get_uninvoiced_premiums staticmethod ¶

mark_entries_for_payroll staticmethod ¶

mark_premiums_as_invoiced staticmethod ¶

PremiumComputationService ¶

compute_insurance_premiums staticmethod ¶

components.premium.public.commands ¶

components.premium.public.cost_types ¶

InsuranceBeneficiary ¶

children class-attribute instance-attribute ¶

from_enrollment_type classmethod ¶

partner class-attribute instance-attribute ¶

primary class-attribute instance-attribute ¶

to_enrollment_type ¶

InsuranceBilledEntity ¶

company class-attribute instance-attribute ¶

partner class-attribute instance-attribute ¶

primary class-attribute instance-attribute ¶

InsuranceCollectionMethod ¶

direct_billing class-attribute instance-attribute ¶

flexben_fund class-attribute instance-attribute ¶

payroll class-attribute instance-attribute ¶

InsuranceContribution ¶

cost class-attribute instance-attribute ¶

discount class-attribute instance-attribute ¶

membership_fee class-attribute instance-attribute ¶

social_fund class-attribute instance-attribute ¶

taxes class-attribute instance-attribute ¶

InsuranceCost dataclass ¶

__setattr__ ¶

cost_components instance-attribute ¶

currency instance-attribute ¶

from_components staticmethod ¶

merge staticmethod ¶

taxed_amount_billed_to_company instance-attribute ¶

taxed_amount_billed_to_primary instance-attribute ¶

untaxed_amount_billed_to_company instance-attribute ¶

untaxed_amount_billed_to_primary instance-attribute ¶

InsuranceCostComponent dataclass ¶

__post_init__ ¶

amount instance-attribute ¶

beneficiary_type instance-attribute ¶

billed_entity instance-attribute ¶

collection_method class-attribute instance-attribute ¶

compare_component_lists staticmethod ¶

contribution_type instance-attribute ¶

currency instance-attribute ¶

enrollment_id class-attribute instance-attribute ¶

group_by_beneficiary_id staticmethod ¶

periodicity class-attribute instance-attribute ¶

service_type instance-attribute ¶

InsuranceService ¶

base class-attribute instance-attribute ¶

extended class-attribute instance-attribute ¶

hospitalization class-attribute instance-attribute ¶

option class-attribute instance-attribute ¶

components.premium.public.dependencies ¶

COMPONENT_NAME module-attribute ¶

PremiumDependency ¶

get_flexben_timeline_for_all_enrollments_of_the_policy abstractmethod ¶

get_legacy_premium_entry_repository abstractmethod ¶

get_premium_repository abstractmethod ¶

get_app_dependency ¶

set_app_dependency ¶

components.premium.public.entities ¶

AgeStrategy ¶

KEEP_EXACT_BIRTHDAY class-attribute instance-attribute ¶

MOVE_BIRTHDAY_TO_FIRST_DAY_OF_MONTH class-attribute instance-attribute ¶

MOVE_BIRTHDAY_TO_JAN_OF_NEXT_YEAR class-attribute instance-attribute ¶

Contract ¶

get_simple_subscription_version_timeline ¶

is_cancelled instance-attribute ¶

policies instance-attribute ¶

BELGIUM_PREMIUM_MIGRATION_WINDOW_END `class-attribute` `instance-attribute` ¶

BELGIUM_PREMIUM_MIGRATION_WINDOW_START `class-attribute` `instance-attribute` ¶

get_premium_entries_for_invoice `staticmethod` ¶

get_premiums_for_local_payroll `staticmethod` ¶

get_premiums_for_payroll `staticmethod` ¶

get_uninvoiced_premiums `staticmethod` ¶

mark_entries_for_payroll `staticmethod` ¶

mark_premiums_as_invoiced `staticmethod` ¶

compute_insurance_premiums `staticmethod` ¶

children `class-attribute` `instance-attribute` ¶

from_enrollment_type `classmethod` ¶

partner `class-attribute` `instance-attribute` ¶

primary `class-attribute` `instance-attribute` ¶

company `class-attribute` `instance-attribute` ¶

partner `class-attribute` `instance-attribute` ¶

primary `class-attribute` `instance-attribute` ¶

direct_billing `class-attribute` `instance-attribute` ¶

flexben_fund `class-attribute` `instance-attribute` ¶

payroll `class-attribute` `instance-attribute` ¶

cost `class-attribute` `instance-attribute` ¶

discount `class-attribute` `instance-attribute` ¶

membership_fee `class-attribute` `instance-attribute` ¶

social_fund `class-attribute` `instance-attribute` ¶

taxes `class-attribute` `instance-attribute` ¶

InsuranceCost `dataclass` ¶

setattr ¶

cost_components `instance-attribute` ¶

currency `instance-attribute` ¶

from_components `staticmethod` ¶

merge `staticmethod` ¶

taxed_amount_billed_to_company `instance-attribute` ¶

taxed_amount_billed_to_primary `instance-attribute` ¶

untaxed_amount_billed_to_company `instance-attribute` ¶

untaxed_amount_billed_to_primary `instance-attribute` ¶

InsuranceCostComponent `dataclass` ¶

amount `instance-attribute` ¶

beneficiary_type `instance-attribute` ¶

billed_entity `instance-attribute` ¶

collection_method `class-attribute` `instance-attribute` ¶

compare_component_lists `staticmethod` ¶

contribution_type `instance-attribute` ¶

currency `instance-attribute` ¶

enrollment_id `class-attribute` `instance-attribute` ¶

group_by_beneficiary_id `staticmethod` ¶

periodicity `class-attribute` `instance-attribute` ¶

service_type `instance-attribute` ¶

base `class-attribute` `instance-attribute` ¶

extended `class-attribute` `instance-attribute` ¶

hospitalization `class-attribute` `instance-attribute` ¶

option `class-attribute` `instance-attribute` ¶

COMPONENT_NAME `module-attribute` ¶

get_flexben_timeline_for_all_enrollments_of_the_policy `abstractmethod` ¶

get_legacy_premium_entry_repository `abstractmethod` ¶

get_premium_repository `abstractmethod` ¶

KEEP_EXACT_BIRTHDAY `class-attribute` `instance-attribute` ¶

MOVE_BIRTHDAY_TO_FIRST_DAY_OF_MONTH `class-attribute` `instance-attribute` ¶

MOVE_BIRTHDAY_TO_JAN_OF_NEXT_YEAR `class-attribute` `instance-attribute` ¶

is_cancelled `instance-attribute` ¶

policies `instance-attribute` ¶

CostPeriod `dataclass` ¶

cost `instance-attribute` ¶

EngineParameters `dataclass` ¶

age_strategy `instance-attribute` ¶

default `staticmethod` ¶

default_adult_age `instance-attribute` ¶

default_child_age `instance-attribute` ¶

prorata_strategy `instance-attribute` ¶

rounding_strategy `instance-attribute` ¶

FeeComponent `dataclass` ¶

eq ¶

hash ¶

amount_before_prorata `instance-attribute` ¶

id `class-attribute` `instance-attribute` ¶

invoice_id `instance-attribute` ¶

num_days `instance-attribute` ¶

LegacyBelgianNormalization `dataclass` ¶

CHILD_AGE_LIMIT_YEARS `class-attribute` `instance-attribute` ¶

enrollments `instance-attribute` ¶

id `instance-attribute` ¶

PremiumEntry `dataclass` ¶