Aviate Revenue Recognition

When Kill Bill generates an invoice, Aviate creates one revenue schedule for each eligible invoice item. The schedule records the invoice, invoice item, account, subscription, plan and phase it came from, together with its currency, total amount, service period and recognition method. It also keeps running recognized and deferred amounts. At creation, the full amount is deferred.

Each schedule is split into dated revenue entries. An entry is recognized once its date is reached. When the full amount of a schedule has been recognized, the schedule is closed.

The recognition method depends only on the type of the invoice item. In this release it cannot be set per plan, product or customer.

Items with a zero or negative amount, and other item types such as taxes and credits, do not get a schedule. Each invoice item has at most one schedule.

For straight-line schedules:

For example, an annual subscription of $1,200.00 for the period from 1 January 2026 to 1 January 2027 (365 days) gives about $3.29 per day:

Monthly amounts are rounded to the cent, so the sum of the twelve rounded months can differ from the total by one cent.

A $500 one-time setup fee is recognized in full on its service start date.

An accounting period groups revenue entries by calendar month. The system identifies each period by a name in the format YYYY-MM (for example, 2026-04). The system assigns each revenue entry to the accounting period corresponding to the month of its date. For example, the system assigns an entry dated 2026-04-17 to the period 2026-04.

A period is either open or closed:

Periods are created automatically, one per calendar month, as invoices are generated. You can also create a period ahead of time. Close a period at month-end once its revenue has been recognized.

When a contract covers several subscriptions (for example a subscription, an implementation service and a support plan), Aviate allocates the contract’s transaction price across them in proportion to their standalone selling prices (SSP):

See Contract Revenue Allocation for details.

Install the Aviate plugin as described in the How to Install the Aviate Plugin guide.

Revenue recognition is disabled by default. To enable it, start Kill Bill with the following system property:

The following properties control revenue recognition:

Revenue schedules are created as invoices are generated. Enable the feature before you start billing the customers whose revenue you want to track.

For details on setting configuration properties, refer to the Kill Bill Configuration Guide.

Full API documentation is available at our API documentation.

All revenue recognition endpoints are under ${KB_URL}/plugins/aviate-plugin/v1/revenue. Every request needs your Aviate token (Authorization: Bearer …​) and your tenant’s Kill Bill API key and secret. Parameters are passed in the query string. Send POST requests with Content-Type: application/json and an empty JSON body ({}).

This screen compares straight-line and immediate revenue: number of schedules, total, recognized and deferred amounts, and the average number of days since invoicing.

When Kill Bill generates an invoice, Aviate creates a revenue schedule for each eligible invoice item and generates its entries (see Recognition Methods). It also creates the monthly accounting periods those entries fall into, if they do not exist yet. Creating a schedule does not recognize any revenue.

A background process runs at the configured interval, once a day by default. Each run:

Revenue belongs to the accounting period of its service date, not to the date the process ran. Revenue for April recognized by a run in May stays in April.

In production, regular runs recognize revenue for each day of the month as it passes. Once a run executes on or after the last day of the month, the system has processed all revenue entries for that month.

The month-end workflow is:

See Closing a Period for the steps.

Periods are created automatically, but you can create one ahead of time. All three parameters are required. The name must be unique, and the end date cannot be before the start date. A successful request returns 201 Created.

Add closed=true or closed=false to list only closed or only open periods.

To view a single period, use GET /v1/revenue/periods/{name}, for example /v1/revenue/periods/2026-04.

Each period includes:

The period summary returns the recognized amount, the deferred (not yet recognized) amount and the number of entries in the period, for all currencies combined:

For one row per currency, use currencySummary instead:

If you bill in more than one currency, use the currency summary. The plain summary adds amounts in different currencies together.

To close a month:

The close is rejected if the period does not exist, is already closed, or still contains unrecognized revenue entries. In the last case the error reports how many entries remain, for example Cannot close period 2026-01: 12 unrecognized entries remain.

If the close is still rejected after a recognition run has taken place on or after the last day of the month, review the remaining entries (see Invoice Adjustments, Credits and Cancellations). You can then override this check with force=true:

Closing a period does not block new invoices, credits or adjustments for that month. See Invoice Adjustments, Credits and Cancellations.

In exceptional cases, a closed period can be reopened for corrections. A successful reopen returns 204 No Content. The request is rejected if the period does not exist or is not closed.

Reopening clears the closed date and closed-by user. Entries in the period that were not yet recognized become eligible again, and the next recognition run can pick them up. Entries that were already recognized are not changed.

The waterfall report shows recognized and deferred revenue for each accounting period, with one row per period and currency:

All parameters are optional:

Each row contains the accounting period, the currency, the recognized amount, the deferred (not yet recognized) amount and the number of entries. The report is returned as JSON, so you can load it into a spreadsheet or another reporting tool.

Total, recognized and deferred amounts and the number of schedules for each plan, across the whole tenant. Takes no parameters.

For each recognition method (straight-line or immediate): total amount, recognized amount, the share recognized so far and the number of schedules, across the whole tenant. Takes no parameters.

Reports are built from two different sources. Their figures can differ after adjustments, credits or cancellations.

In entry-based reports, "deferred" is the total of entries not yet recognized.

Each subscription in the contract is a contract term. Consider a contract with three subscriptions whose first invoice totals $15,000:

Using relative SSP allocation:

The implementation fee ($3,000 charged) receives an allocation of $4,411.76 because relative-SSP allocation distributes the total transaction price proportionally. Any rounding difference is assigned to the last term, so the allocations add up exactly to the transaction price.

The following rules apply:

We recommend setting explicit SSPs for every plan and phase used in contracts, so that allocations are consistent and auditable.

SSPs are set per plan, phase and currency, with a validity period. You can manage them on the SSP screen in Aviate, or through the API:

A successful request returns 201 Created. To list all SSPs, use GET /v1/revenue/ssp. To delete one, use DELETE /v1/revenue/ssp/{id}. Deleting an SSP removes it permanently and does not change allocations that were already made.

currency and transactionPrice are required. The response lists the resulting allocation for each contract term.

To view a contract’s allocations without changing them, send a GET request to the same path. For each term, the result shows the plan, phase, list price, SSP, SSP ratio, allocated amount, transaction price, currency and allocation method.

List revenue schedules with any combination of these filters:

Results are returned newest first.

Contract allocations and the revenue schedules of a contract are available through two calls. The contract ID is a UUID.

Get the schedule of an invoice item, using its Kill Bill invoice item ID:

Get a schedule by its ID. Schedule IDs are numbers and are returned in the schedule details.

List the revenue entries of a schedule, showing each entry’s date, amount, accounting period and whether it has been recognized:

Revenue schedules and entries are derived from invoices. You cannot create, edit or delete them directly.

A customer is invoiced $31.00 for a monthly plan covering 2026-01-01 to 2026-02-01.

A customer is invoiced $90.00 for a quarterly plan covering 2026-01-01 to 2026-04-01, which is 90 days. The daily amount is $1.00:

At the end of January, $31.00 is recognized and $59.00 is still deferred.

A customer is invoiced $100.00 for 2026-04-01 to 2026-05-01 (30 days). Each of the first 29 entries is $3.333333333 (100 ÷ 30, rounded to nine decimals). The last entry, on 2026-04-30, is $3.333333343, so that the 30 entries add up to exactly $100.00.

A customer is invoiced a fixed $250.00 setup fee with a service start date of 2026-04-15. Aviate creates an immediate schedule with one entry of $250.00 in period 2026-04. The first run on or after 2026-04-15 recognizes the full amount and closes the schedule.

On 2026-05-02, the finance team closes April:

If unrecognized entries had remained in April, step 3 would have been rejected with Cannot close period 2026-04: N unrecognized entries remain. After reviewing them, the team could close the month with force=true.