> For the complete documentation index, see [llms.txt](https://knowledge.maica.com.au/maica-knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledge.maica.com.au/maica-knowledge-base/maica-administration-guide/residential-aged-care/fee-adjustment-service.md).

# Fee Adjustment Service

When a fee rate change takes effect on a date that falls inside a period that has already been billed, the resident has been charged at the old rate for days that should have been charged at the new rate. The fee adjustment service generates a compensating invoice for the difference, so the resident's account reflects the correct rate without the original invoices having to be reversed.

This article explains what the service does, when it runs, and how the adjustment is calculated. It is written for administrators and power users who support the billing process.

{% hint style="info" %}
This service works hand in hand with the [Statement reconciliation service](https://knowledge.maica.com.au/maica-knowledge-base/maica-administration-guide/residential-aged-care/statement-reconciliation-service.md). Together they keep the two ways a rate can be corrected (a detected or manual rate change, and a payment statement reconciliation) from adjusting the same period twice.
{% endhint %}

## What the service does

The service produces a single adjustment for the retrospective window, which runs from the new rate's start date to the last period already billed at the old rate. The adjustment is either:

* **An additional charge**, when the rate increased, or
* **A credit**, when the rate decreased or the fee ceased.

The adjustment is recorded as an invoice line item marked as a **Rate Adjustment**, raised against the resident's service agreement through the shared adjustment invoice process. It does not alter the original invoices. The adjustment invoice records the retrospective window as its billing period, and the line is dated the day the adjustment is raised.

{% hint style="warning" %}
The adjustment quantity is derived from the existing invoice line items in the window, not recalculated from calendar days. The original line items already reflect any leave adjustments, pro-rata splits, or cap limits applied when they were billed, so reusing them keeps the adjustment consistent with the original charge.
{% endhint %}

## When the service runs

There are two ways the service is triggered. Both follow the same calculation logic, so the result is the same regardless of how the rate change arose.

### After an automated fee update or cessation

When a rate change is applied to an agreement item (for example following a detected government rate change), the fee update process creates the new agreement item and then invokes the adjustment service for any billing already stamped at the old rate inside the window. The same happens when a fee ceases: the service is invoked with an effective new rate of zero, producing a full credit for any billing after the cessation date.

{% hint style="info" %}
For how rate changes are detected and applied, see [Fee detection and rate updates](broken://pages/3c4471bff8b9aadb01aa7d0f1f31cddb161e29e8).
{% endhint %}

### After a manual rate change

When a provider records a rate change in the **Manage RACS Agreement** component and the new agreement item's start date is earlier than the period last billed on the previous item, the save handler invokes the same adjustment service. This lets providers generate adjustments from manually entered rate changes, not only from changes detected from Services Australia.

### Follow-up adjustments

Where a second rate change falls on a window an earlier adjustment has already corrected, a follow-up adjustment is raised for the additional difference. The earlier adjustment has already netted any Statement Reconciliation in the window, so the follow-up does not net it again.

## How the adjustment is calculated

The calculation follows a consistent sequence:

1. **Determine the window.** The window starts at the new rate's start date (or the cessation date) and ends at the last period billed on the previous agreement item. If nothing was billed in that window, or the new item starts after the last billed period, the service exits cleanly and no adjustment is created.
2. **Find the affected line items.** The service reads the existing line items on the previous agreement item that fall within the window. Line items already marked as a Rate Adjustment or a Statement Reconciliation are excluded, so a period is never adjusted twice.
3. **Work out the adjustable quantity.** Each line item records the **Billing Period Start** of the period it billed, and its service date is the period end. The service uses that billed period, whatever the fee's current frequency, so a period cut short by the fee's start or end date is counted exactly. Where a billed period straddles the window start, the billed quantity is split proportionally so that only the days on or after the window start are adjusted. Where a line has no usable period start, the period is rebuilt from the calendar: a month is the whole month of the service date, a week is the seven days ending on it, and a day or one-off is the single day.
4. **Apply the rate difference.** The adjustment uses the difference between the new and old rate. For a cessation, the new rate is zero, so the difference is the full old rate as a credit.
5. **Deduplicate against statement reconciliation.** Before creating the adjustment, the service checks for existing **Statement Reconciliation** line items covering the same agreement item and period. If reconciliation has already corrected some or all of the difference, only the residual amount is generated. Where a prior reconciliation has already over-corrected in the opposite direction, no adjustment is raised, so a deliberate manual correction is not reversed.

If, after these steps, there is nothing left to adjust (the rate is unchanged, the quantity is zero, or reconciliation already covered it), no adjustment invoice is created.

{% hint style="info" %}
The departure process reads billed periods the same way, so a departure credit after a mid-period rate change credits each part of the period at the rate it was billed at.
{% endhint %}

{% hint style="success" %}
Because the service excludes prior Rate Adjustment line items and nets off existing Statement Reconciliation line items, it is safe for the same rate change to be processed by both the detection path and the reconciliation path without double-charging or double-crediting the resident.
{% endhint %}

## What this service does not do

The fee adjustment service works entirely on existing Maica data. It does not call Services Australia, it does not create or end-date agreement items (that is the fee update process), and it does not perform cap validation or leave counting. Its single responsibility is to calculate and raise the adjustment for an already-billed period.
