Glossary

Risk covered (sum_assured)

What is sum_assured?

Risk covered represents the total coverage amount (in cents) that a policyholder is insured for. It's the maximum amount that can be paid out under the policy.

How it's set:

Quote Hook (getQuote)

The getQuote function returns a QuotePackage which includes sum_assured as an optional field.

const getQuote = (data) => {
   // Do the math and logic to calculate the premium, benefits, etc.
   // using `data`, hardcoded rating tables, data stores, or external services/APIs
  const premium = ...;

  const quotePackage = new QuotePackage({
    // Below are standard fields for all products
    package_name: 'Dino protection', // The name of the "package" of cover
    sum_assured: data.life_cover, // Set the total, aggregated cover amount
    base_premium: premium, // Should be an integer, cents
    suggested_premium: premium, // Should be an integer, cents
    billing_frequency: 'monthly', // Can be monthly or yearly
    module: {
      // Save any data, calculations, or results here for future re-use.
      ...data, // We normally inject the full input data here
    },
    input_data: {...data},
  });
  return [quotePackage];
}

Application Hook (getApplication)

The getApplication function receives the quote package (with its sum_assured) as input and returns a Application with sum_assured (required on the type).

function getApplication(data, policyholder, quotePackage) {
  // ...
  return new Application({
    package_name: quotePackage.package_name,
    sum_assured: quotePackage.sum_assured,
    monthly_premium: quotePackage.suggested_premium,
    // ...
  });
}

Full Flow

The sum_assured flows through the entire lifecycle:

1. Quote hook — product module code calculates and returns sum_assured
2. Quote package — stored on the quote package record
3. Application hook (getApplication) — receives the quote package (including sum_assured) as input, typically passes it through or recalculates
4. Application — stored on the application record
5. Policy — carried over when the policy is issued (via getPolicy hook)
6. Claims — used as the default requestedAmount when a claim is linked So sum_assured originates in the product module's quote hook and propagates through the entire policy lifecycle.

Alteration packages

When an alteration is applied to a policy, the sum_assured can be changed, triggering a dedicated PolicySumAssuredUpdated event.

What is it NOT used for:

Billing

It is not directly involved in premium/billing calculations. Those use separate fields like monthlyPremium, basePremium, and billingAmount.

basePremium

What is base_premium?

base_premium represents the minimum allowed monthly premium for a policy. It includes risk pricing and platform fees and acts as a floor — no billing amount can go below it.

Quote Hook

The [getQuote](doc:quote-hook) function returns a QuotePackage which includes base_premium as a required field.

const getQuote = (data) => {
  const premium = ...;

  const quotePackage = new QuotePackage({
    package_name: 'Dino protection',
    sum_assured: data.life_cover,
    base_premium: premium,       // Minimum allowed premium (integer, cents)
    suggested_premium: premium,  // Suggested premium ≥ base_premium (integer, cents)
    billing_frequency: 'monthly',
    module: { ...data },
    input_data: { ...data },
  });
  return [quotePackage];
}

📘

suggestedPremium

If suggested_premium is not provided, it defaults to base_premium

Application Hook

The [getApplication](doc:application-hook) function receives the quote package and returns an Application with base_premium (required). A validation enforces that the monthly premium (or suggested_premium) is never less than base_premium

So base_premium originates in the product module's Quote Hook and propagates through the entire policy lifecycle.

Alteration Packages

When an alteration is applied to a policy, base_premium can be changed.

Relationship to Other Premium Fields

Where it exists per entity

suggested_premium

Suggested premium represents the recommended monthly premium amount (in cents) that a policyholder should be charged. It is a Quote-only field — it exists on the QuotePackage but does not carry forward as its own field. Instead, it becomes monthly_premium on the Application and Policy.

How it's set:

Quote Hook

The [getQuote](doc:quote-hook) returns a QuotePackage which includes suggested_premium as an optional field. If not provided, it defaults to base_premium.

const getQuote = (data) => {
  const premium = ...;

  const quotePackage = new QuotePackage({
    package_name: 'Dino protection',
    sum_assured: data.life_cover,
    base_premium: premium,       // Minimum allowed premium (integer, cents)
    suggested_premium: premium,  // Recommended premium ≥ base_premium (integer, cents)
    billing_frequency: 'monthly',
    module: { ...data },
    input_data: { ...data },
  });
  return [quotePackage];
}

📘

suggested_premium default

If suggested_premium is omitted, it falls back to base_premium

Application Hook

The [getApplication](doc:application-hook) function receives the quote package (with its suggested_premium) and maps it to monthly_premium on the Application. The default product module code does this explicitly:

// ... getApplication function
  return new Application({
    package_name: quotePackage.package_name,
    sum_assured: quotePackage.sum_assured,
    monthly_premium: quotePackage.suggested_premium,  // ← becomes monthly_premium
    base_premium: quotePackage.base_premium,
    module: { ...quotePackage.module },
    currency: quotePackage.currency,
  });

Override at application creation: When creating an application via the API, a monthly_premium can optionally be passed in. If provided, it overrides the quote's suggested_premium.

By the time a policy is issued, suggested_premium no longer exists as its own field.