Application Cancellation Reasons Hook

Overview

The getApplicationCancellationReasons() hook allows you to customise the list of cancellation reasons that can be captured when a pending application is cancelled. This is useful when the platform's default reasons don't match your product, your distribution channel, or your regulatory requirements.

The reasons are split into two lists: those available when the client initiates the cancellation, and those available when the insurer initiates it. The lists returned by this hook are used to populate the cancellation form on the Root management dashboard, are returned by the get allowed application cancellation reasons endpoint, and are used to validate the cancellation_type supplied to the cancel an application endpoint.

📘

Relationship to the Module Display Data hooks

This hook follows the same opt-in pattern as the getApplicationModuleDisplayData() and getPolicyModuleDisplayData() hooks — a feature flag plus a product module setting plus a product module function. If you have implemented one of those, this works the same way.

Enabling the hook

Two configuration steps are required to enable this functionality.

Opt-in

Contact Root support to enable the override_application_cancellation_reasons feature flag for your organisation.

Product module setting

In your product module's .root-config.json file, enable the override setting:

{
  "productModuleName": "Root Funeral",
  "productModuleKey": "root_funeral",
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "host": "http://localhost:4000",
  "stack": "root-node-20",
  "settings": {
    "overrideApplicationCancellationReasons": true,
    ...
  }
}

If either the feature flag or this setting is not enabled, the platform uses the default cancellation reasons (see below) and your getApplicationCancellationReasons() function is not called.

Configuring the getApplicationCancellationReasons() function

Define the function in your product module code with the following signature:

function getApplicationCancellationReasons(application, policyholder, currentUser) {
  // Custom logic
  return {
    client: [ ... ],
    insurer: [ ... ],
  };
}

Function parameters

• application - The application being cancelled, including all standard fields and the module object containing product-specific data.
• policyholder - The policyholder linked to the application.
• currentUser - Optional. Information about the user initiating the cancellation, including their user_id, email, and permissions.

Return value

The function must return an object with two properties, each an array of reason-code strings:

• client - Array of strings. The cancellation reasons available when the cancellation_requestor is client.
• insurer - Array of strings. The cancellation reasons available when the cancellation_requestor is insurer.

Both arrays are required. If the function returns anything other than this shape, the platform falls back to the default reasons.

Default cancellation reasons

If overriding is not enabled (or the hook returns an invalid value), the platform provides these defaults:

Example: custom reason lists

function getApplicationCancellationReasons(application, policyholder, currentUser) {
  return {
    client: [
      'changed_mind',
      'premium_too_high',
      'found_better_cover',
      'other',
    ],
    insurer: [
      'failed_underwriting',
      'duplicate_application',
      'captured_in_error',
      'other',
    ],
  };
}

When a user cancels this application, only the reasons above will be accepted for the corresponding requestor. Supplying a cancellation_type that is not in the relevant list returns a validation error from the cancel an application endpoint.

How the reasons are used

• Dashboard: the cancellation form on the application page is populated with the reasons returned for the selected requestor.
• API (read): the get allowed application cancellation reasons endpoint returns the resolved client and insurer lists.
• API (validation): the cancel an application endpoint validates the supplied cancellation_type against the resolved list for the supplied cancellation_requestor.

📘

Safe fallback

If the hook throws an error or returns an invalid value, the platform logs the error and falls back to the default reason lists, so application cancellation continues to work.