Taxation Configuration Guide

Tax configurations define how insurance premium tax (IPT) is calculated for different scenarios. This guide explains how to set up and manage tax configurations in the Tax Management System.

Overview

A tax configuration specifies:

• Tax Name and Code - Human-readable name and unique identifier
• Applicable Countries - Countries where this tax applies
• Coverage Groups - Which coverages this tax applies to
• Tax Rules - How to calculate the tax
• Rate Tables - Tax rates with effective dates
• Calculation Method - Percentage or fixed amount

Accessing Tax Configuration

Navigate to Tax Configurations from the sidebar menu to manage tax configurations.

Creating a Tax Configuration

Basic Information

1. Click "Create Tax Configuration"
2. Fill in the basic information:
   • Name - Human-readable name (e.g., "UK Motor Insurance IPT")
   • Tax Code - Unique identifier (e.g., "UK_MOTOR_IPT")
   • Country Codes - Countries where this tax applies (e.g., GB, IE)
   • Currency - Currency for tax amounts (e.g., GBP, EUR)

Calculation Settings

Configure how the tax is calculated:

• Calculation Based On - What the tax is calculated from:

  • Premium - Tax based on premium amount
  • Limit - Tax based on policy limit

• Calculation Type - How the tax amount is determined:

  • Percentage - Tax as a percentage of the base amount
  • Fixed - Tax as a fixed amount

• Payable By - Who pays the tax:

  • Insurer - Insurance company pays
  • Policyholder - Policyholder pays

• Administered By - Who administers the tax:

  • Insurer - Insurance company administers
  • Policyholder - Policyholder administers

• Status - Configuration status:

  • Active - Currently in use
  • Inactive - Not in use
  • Draft - Still being developed

Coverage Groups

Define which coverages this tax applies to by creating coverage groups:

1. Click "Add Coverage Group"
2. Specify:
   • Group Name - Descriptive name for the group
   • Coverages - Select the coverages that belong to this group
   • Notes - Any additional information about this group

Example Coverage Groups

• Motor Coverages - Includes Motor, Motor Fleet, Motorcycle
• Property Coverages - Includes Property, Home, Commercial Property
• Liability Coverages - Includes Public Liability, Professional Indemnity

Tax Rules and Rate Tables

For each coverage group, define tax rules in a rate table:

Rate Table Structure

A rate table contains entries with:

• Effective From Date - When this rate becomes effective
• Tax Rules - Rules for calculating tax under this rate

Adding a Rate Entry

1. Click "Add Rate Entry" in a coverage group
2. Set the effective date
3. Add tax rules for that date

Tax Rule Types

1. Simple Rule (Flat Amount)

Use when the tax is always the same amount:

• Amount - The tax amount
• Amount Type - How to interpret the amount:
  • Percentage - Percentage of base amount
  • Fixed - Fixed currency amount
  • Per Mille - Per thousand (0.1%)
  • Factor - Multiplier
• Default Rule - Whether this is the fallback rule
• Applies to Standard Premium - Whether it applies to base premium

2. Complex Rule (With Conditions)

Use when tax varies based on conditions:

• All simple rule settings plus:
• Conditions - Criteria that must be met for this rule to apply

3. Function Rule (Custom Formula)

Use for complex calculations:

• Function Script - Custom calculation formula
• Return Type - Expected return type
• Additional Premium Types - Which additional premiums to include

Rule Conditions

Conditions specify when a rule applies:

For each condition:

• Coverage Input Name - The input field to check (from coverage configuration)
• Coverage Input Type - Data type of the input
• Operator - Comparison:
  • Equal To - Value must equal
  • Not Equal To - Value must not equal
  • Greater Than - Value must be greater than
  • Greater Than or Equal To - Value must be greater than or equal
  • Less Than - Value must be less than
  • Less Than or Equal To - Value must be less than or equal
• Value - The value to compare against (based on input type)

Example Tax Rules

Simple Rule:

Effective From: 2024-01-01
Rule:
  Type: Simple
  Amount: 12
  Amount Type: Percentage
  Default: Yes
  Applies to Standard Premium: Yes

This applies a 12% tax to all premiums.

Complex Rule:

Effective From: 2024-01-01
Rule:
  Type: Complex
  Amount: 20
  Amount Type: Percentage
  Conditions:
    - Input: vehicleValue
      Type: Number
      Operator: Greater Than
      Value: 50000

This applies 20% tax only when vehicle value exceeds £50,000.

Function Rule:

// Custom calculation formula
baseRate = 0.12 (12% base rate)
valueFactor = min(vehicleValue / 100000, 1.5)
return baseRate * valueFactor

Custom Properties

Add custom key-value pairs for additional metadata:

• Regulatory references
• Internal codes
• Integration identifiers
• Audit information

Notes

Use notes to document:

• Regulatory requirements
• Calculation logic explanations
• Historical changes
• Integration notes

Managing Rate Changes

Tax rates often change over time. Use the rate table to manage changes:

1. Add a new rate entry with the new effective date
2. Define the new tax rules
3. The system automatically uses the correct rate based on the date

Example Rate History

2020-01-01: 10% standard rate
2022-01-01: 11% standard rate
2024-01-01: 12% standard rate

Rule Evaluation Order

The system evaluates rules in order:

1. Check each rule's conditions
2. First rule with matching conditions is applied
3. If no conditions match, the default rule is used
4. If no default rule exists, no tax is applied

Best Practices

Rule Design

• Start Simple - Begin with simple rules, add complexity as needed
• Use Defaults - Always have a default rule for fallback
• Test Thoroughly - Use the tax calculator to test scenarios
• Document Logic - Use notes to explain complex rules

Condition Design

• Specific to General - Order conditions from most specific to most general
• Avoid Overlap - Ensure conditions don't create ambiguity
• Use Available Inputs - Only use inputs defined in coverage configurations
• Test Edge Cases - Consider boundary values in conditions

Rate Management

• Plan Ahead - Add future rate entries before they take effect
• Document Changes - Use notes to explain why rates changed
• Review Regularly - Periodically review and update rates
• Version Control - Track changes for audit purposes

Function Rules

• Keep Simple - Avoid overly complex scripts
• Test Extensively - Test with various input combinations
• Document Well - Add comments in the script
• Error Handling - Include error handling in scripts

Common Use Cases

Standard IPT

Name: UK Motor IPT
Code: UK_MOTOR_IPT
Countries: GB
Currency: GBP
Calculation Based On: Premium
Calculation Type: Percentage
Payable By: Insurer
Coverage Groups:
  - Motor Coverages
Rate Table:
  2024-01-01:
    - Rule: Simple, 12%, Default

Tiered Tax

Name: High Value Vehicle Tax
Code: HIGH_VALUE_TAX
Rate Table:
  2024-01-01:
    - Rule: Complex, 12%, Default
    - Rule: Complex, 20%, Conditions: [vehicleValue > 50000]
    - Rule: Complex, 25%, Conditions: [vehicleValue > 100000]

Complex Calculation

Name: Custom Calculation Tax
Code: CUSTOM_TAX
Rate Table:
  2024-01-01:
    - Rule: Function
      Script: |
        def base = premium * 0.12;
        if (vehicleValue > 75000) {
          base *= 1.5;
        }
        return base;

Integration with Coverage Configurations

Tax configurations reference coverage configurations:

• Coverage groups use coverage IDs from coverage configurations
• Rule conditions use input names from coverage configurations
• Data types must match between coverage and tax configurations

Ensure:

• Coverage IDs are correct
• Input names match exactly
• Data types are consistent
• Country codes align

Testing

Use the Tax Calculator to test your configurations:

1. Navigate to Admin > Tax Calculator
2. Select a tax configuration
3. Enter test scenarios
4. Review calculated tax amounts
5. Verify rule application

Troubleshooting

Rules Not Applying

• Problem: Expected rule not being applied
• Solution: Check condition order and default rule settings

Incorrect Tax Amounts

• Problem: Tax calculation seems wrong
• Solution: Verify amount type (percentage vs fixed) and base amount

Conditions Not Matching

• Problem: Conditions not triggering as expected
• Solution: Check input names, data types, and comparison values

Rate Not Changing

• Problem: Old rate still being used
• Solution: Verify effective date and system date

Function Errors

• Problem: Function rule failing
• Solution: Check script syntax and variable names