From 094e9bf55b231f2d1daae15586e2ea0767c9128b Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Mon, 19 Oct 2026 13:22:49 +0530 Subject: [PATCH 1/5] Updated rev rec doc --- .../preview/aviate-revenue-recognition.adoc | 588 +++++++++++++----- 1 file changed, 444 insertions(+), 144 deletions(-) diff --git a/userguide/preview/aviate-revenue-recognition.adoc b/userguide/preview/aviate-revenue-recognition.adoc index c05366a7f..10ef8daf9 100644 --- a/userguide/preview/aviate-revenue-recognition.adoc +++ b/userguide/preview/aviate-revenue-recognition.adoc @@ -4,43 +4,78 @@ include::{sourcedir}/includes/insider-preview-card.adoc[] == Introduction -The Aviate Revenue Recognition module provides tools for managing when and how revenue is recognized from your subscriptions and contracts. It supports the standard accounting practices defined by ASC 606 (Revenue from Contracts with Customers), and it gives finance teams visibility into recognized vs. deferred revenue through managed accounting periods. +The Aviate Revenue Recognition module manages when revenue is recognized from the invoices that Kill Bill generates. It spreads each invoiced amount over the period in which the service is delivered, and tracks how much of it has been recognized and how much is still deferred. Finance teams get visibility into recognized vs. deferred revenue through monthly accounting periods that they can close and reopen. + +The module applies concepts from ASC 606 (Revenue from Contracts with Customers): revenue is recognized as the service is delivered. Aviate calculates and reports revenue from billing data. It does not post entries to a general ledger or export journals. Your finance team remains responsible for confirming that the resulting treatment meets the accounting standards that apply to you. Key capabilities include: -* *Accounting periods* -- monthly periods that can be opened, closed, and reported on -* *Revenue schedules* -- automatic recognition of revenue across the term of a contract -* *Contract-aware allocation* -- revenue allocated across multiple performance obligations using relative standalone selling prices -* *Waterfall reports* -- period-by-period view of recognized and deferred revenue +* *Automatic revenue schedules* -- every eligible invoice item gets a schedule that spreads its amount over the item's service period +* *Daily recognition* -- a background process recognizes revenue as each day of service is delivered +* *Accounting periods* -- monthly periods that are created automatically and can be closed, reopened and reported on +* *Reports* -- period summaries, a period-by-period waterfall of recognized and deferred revenue, revenue by plan and recognition rate +* *Schedule lookups* -- schedules and their daily entries by invoice item, account, subscription, plan, currency or contract == Key Concepts -=== Accounting Periods +=== Revenue Schedules and Entries -An accounting period represents a calendar month during which revenue recognition entries are recorded. Each period follows a simple lifecycle: +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. -* *OPEN* -- entries can be added or modified -* *CLOSED* -- entries are frozen; no changes allowed -* *REOPENED* -- a closed period has been reopened by an administrator (for corrections) +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. -Periods are auto-created monthly (named `2026-01`, `2026-02`, etc.) as invoices are generated. They can be explicitly closed at month-end to freeze the financials. +[[revrec-recognition-methods]] +=== Recognition Methods -=== Revenue Recognition Schedules +The recognition method depends only on the type of the invoice item. It cannot be configured per plan, product or customer. + +[cols="1,1,2", options="header"] +|=== +| Invoice item type | Recognition method | How the amount is spread -When an invoice is generated, the system creates recognition entries that spread the revenue across the appropriate periods. For example: +| Recurring +| Straight-line +| Evenly, one entry per day of the service period -* A $1,200 annual subscription generates $100/month recognition entries across 12 periods -* A $500 one-time setup fee is recognized immediately (or spread, depending on your rules) -* Usage revenue is recognized in the period it was consumed +| Usage +| Straight-line +| Evenly, one entry per day of the item's service period + +| Fixed (one-time) +| Immediate +| One entry for the full amount on the service start date + +| External charge +| Immediate +| One entry for the full amount on the service start date +|=== -=== Contract Revenue Allocation (ASC 606) +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: + +* The service period runs from the item's start date up to, but *not including*, its end date. A 1 January to 1 February period is 31 days. +* The daily amount is the total divided by the number of days, rounded to nine decimal places. +* The last day takes any rounding difference, so the entries always add up exactly to the schedule total. + +For example: + +* A $1,200 annual subscription billed for 1 January 2026 to 1 January 2027 is spread over 365 days, at about $3.29 a day. January (31 days) receives $101.92, February (28 days) $92.05 and April (30 days) $98.63. +* A $500 one-time setup fee is recognized in full on its service start date. + +=== Accounting Periods -When a contract includes multiple performance obligations (e.g., a subscription + setup + support), revenue is allocated proportionally based on *standalone selling prices* (SSP). This ensures compliance with ASC 606: +An accounting period groups revenue entries by calendar month. Periods are identified by name, in the format `YYYY-MM` (for example `2026-04`). Every revenue entry belongs to the period named after the month of its date. For example, an entry dated `2026-04-17` belongs to period `2026-04`. -. Identify the performance obligations in the contract -. Determine the standalone selling price (SSP) for each obligation -. Allocate the total transaction price proportionally -. Recognize revenue as each obligation is satisfied +A period is either *open* or *closed*: + +* *Open* -- the daily recognition process recognizes the period's entries as their dates are reached. +* *Closed* -- the daily recognition process no longer recognizes the period's remaining entries, and the date and user that closed it are recorded. A closed period can be reopened, which makes it open again. + +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. + +[NOTE] +*Note:* Closing a period does not block billing. Kill Bill still accepts invoices, credits, adjustments and payments dated in a closed period, and adjustments still update the affected revenue schedules. See <>. == Getting Started with Revenue Recognition @@ -50,56 +85,212 @@ Install the Aviate plugin as described in the https://docs.killbill.io/latest/ho === Enabling Revenue Recognition -To enable revenue recognition, start Kill Bill with the following system property: +Revenue recognition is disabled by default. To enable it, start Kill Bill with the following system property: [source,bash] ---- com.killbill.billing.plugin.aviate.enableRevenueRecognition=true ---- +The following properties control revenue recognition: + +[cols="2,1,3", options="header"] +|=== +| Property | Default | Description + +| `com.killbill.billing.plugin.aviate.enableRevenueRecognition` +| `false` +| Set to `true` to create revenue schedules for new invoices and to start the daily recognition process. + +| `com.killbill.billing.plugin.aviate.revenueRecognition.delaySeconds` +| `86400` (one day) +| How often the recognition process runs, in seconds. +|=== + +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 https://docs.killbill.io/latest/userguide_configuration.html[Kill Bill Configuration Guide]. === Using Revenue Recognition APIs Full API documentation is available at https://apidocs.killbill.io/aviate-revrec[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 (`{}`). + + +== How Revenue Is Recognized + +=== Schedule Creation + +When Kill Bill generates an invoice, Aviate creates a revenue schedule for each eligible invoice item and generates its entries (see <>). It also creates the monthly accounting periods those entries fall into, if they do not exist yet. + +=== Daily Recognition + +A background process runs at the configured interval, once a day by default. Each run: + +* Recognizes every unrecognized entry dated *on or before the current date (UTC)* in an open period, including entries dated today. +* Updates each affected schedule's recognized and deferred amounts. +* Closes a schedule once its full amount has been recognized. + +=== Recognizing Revenue for a Specific Month + +In production, revenue for a month is recognized by the regular runs as its days pass. All of a month's entries have been processed once a run has taken place on or after the last day of that month. + +The month-end workflow is: + +. Wait for a recognition run on or after the last day of the month. +. Review the month with the period summary. +. Close the period. + +See <> for the steps. + +==== Running Recognition On Demand + +The `triggerRevenueRecognition` endpoint runs recognition immediately, up to a date that you choose: + +[source,bash] +---- +curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/revenue/triggerRevenueRecognition?recognitionDate=2026-04-30" \ + -H "Authorization: Bearer ${ID_TOKEN}" \ + -H "X-Killbill-ApiKey: ${API_KEY}" \ + -H "X-Killbill-ApiSecret: ${API_SECRET}" \ + -H "Content-Type: application/json" \ + -d '{}' +---- + +[cols="1,1,3", options="header"] +|=== +| Parameter | Required | Description + +| `recognitionDate` +| Yes +| Recognize entries dated on or before this date (`YYYY-MM-DD`) +|=== + +A successful request returns `204 No Content`. A missing `recognitionDate` is rejected with `recognitionDate is required`. + +The run works like a daily run, except that it uses `recognitionDate` instead of the current date: + +* It recognizes every unrecognized entry dated on or before `recognitionDate` in an open period, and updates and closes schedules in the same way. +* It applies to *all accounts of the tenant*. It cannot be limited to an account, a contract or a single month. +* A `recognitionDate` in the future recognizes revenue for service that has not been delivered yet. +* Recognized entries cannot be reverted. Reopening a period does not change entries that were already recognized. +* Do not run it at the same time as the scheduled recognition run. + == Managing Accounting Periods +=== Creating a Period + +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`. + +[source,bash] +---- +curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/revenue/periods?periodName=2026-05&startDate=2026-05-01&endDate=2026-05-31" \ + -H "Authorization: Bearer ${ID_TOKEN}" \ + -H "X-Killbill-ApiKey: ${API_KEY}" \ + -H "X-Killbill-ApiSecret: ${API_SECRET}" \ + -H "Content-Type: application/json" \ + -d '{}' +---- + +[NOTE] +*Note:* Revenue entries are assigned to periods by name. Use the `YYYY-MM` format with the first and last day of the month. A period with any other name receives no revenue entries. + === Listing Periods +Add `closed=true` or `closed=false` to list only closed or only open periods. + [source,bash] ---- -curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/periods" \ +curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/periods?closed=false" \ -H "Authorization: Bearer ${ID_TOKEN}" \ -H "X-Killbill-ApiKey: ${API_KEY}" \ -H "X-Killbill-ApiSecret: ${API_SECRET}" ---- -Response: +To view a single period, use `GET /v1/revenue/periods/{name}`, for example `/v1/revenue/periods/2026-04`. + +Each period includes: + +[cols="1,3", options="header"] +|=== +| Field | Description + +| `periodName` +| The period name, for example `2026-04` + +| `startDate`, `endDate` +| The first and last day of the period + +| `closed` +| `true` if the period is closed + +| `closedDate`, `closedBy` +| When and by whom the period was closed. Empty for open periods. +|=== -[source,json] +=== Viewing a Period Summary + +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: + +[source,bash] +---- +curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/periods/2026-04/summary" \ + -H "Authorization: Bearer ${ID_TOKEN}" \ + -H "X-Killbill-ApiKey: ${API_KEY}" \ + -H "X-Killbill-ApiSecret: ${API_SECRET}" +---- + +For one row per currency, use `currencySummary` instead: + +[source,bash] ---- -[ - { "name": "2026-01", "status": "CLOSED", "totalRecognized": 45230.00 }, - { "name": "2026-02", "status": "OPEN", "totalRecognized": 38100.00 } -] +curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/periods/2026-04/currencySummary" \ + -H "Authorization: Bearer ${ID_TOKEN}" \ + -H "X-Killbill-ApiKey: ${API_KEY}" \ + -H "X-Killbill-ApiSecret: ${API_SECRET}" ---- +If you bill in more than one currency, use the currency summary. The plain summary adds amounts in different currencies together. + +[[revrec-closing-period]] === Closing a Period +To close a month: + +. Check that a recognition run has taken place on or after the last day of the month. +. Review the period summary. +. Close the period. A successful close returns `204 No Content`. + [source,bash] ---- curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/revenue/periods/2026-01/close" \ -H "Authorization: Bearer ${ID_TOKEN}" \ -H "X-Killbill-ApiKey: ${API_KEY}" \ - -H "X-Killbill-ApiSecret: ${API_SECRET}" + -H "X-Killbill-ApiSecret: ${API_SECRET}" \ + -H "Content-Type: application/json" \ + -d '{}' ---- -The system validates that all invoices in the period have recognition entries before allowing the close. If unrecognized entries exist, the close is rejected with a list of the affected invoices. +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`. -=== Reopening a Period (Admin Only) +After reviewing the remaining entries, you can override this check with `force=true`: -In exceptional cases, a closed period can be reopened for corrections: +[source,bash] +---- +curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/revenue/periods/2026-01/close?force=true" \ + -H "Authorization: Bearer ${ID_TOKEN}" \ + -H "X-Killbill-ApiKey: ${API_KEY}" \ + -H "X-Killbill-ApiSecret: ${API_SECRET}" \ + -H "Content-Type: application/json" \ + -d '{}' +---- + +A month that contains a mid-period cancellation or adjustment can only be closed with `force=true` (see <>). + +=== Reopening a Period + +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. [source,bash] ---- @@ -108,170 +299,279 @@ curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/revenue/periods/2026-01/reopen" -H "X-Killbill-ApiKey: ${API_KEY}" \ -H "X-Killbill-ApiSecret: ${API_SECRET}" \ -H "Content-Type: application/json" \ - -d '{ "reason": "Correcting misclassified setup fee" }' + -d '{}' ---- -[NOTE] -*Note:* Reopening a period requires administrator privileges and creates an audit trail entry. +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. -== Revenue Waterfall Report +== Revenue Reports -The waterfall report shows recognized revenue by period across all contracts: +=== Revenue Waterfall + +The waterfall report shows recognized and deferred revenue for each accounting period, with one row per period and currency: [source,bash] ---- -curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/waterfall?from=2026-01&to=2026-06" \ +curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/reports/waterfall?startPeriod=2026-01&endPeriod=2026-06¤cy=USD" \ -H "Authorization: Bearer ${ID_TOKEN}" \ -H "X-Killbill-ApiKey: ${API_KEY}" \ -H "X-Killbill-ApiSecret: ${API_SECRET}" ---- -Response: +All parameters are optional: + +[cols="1,3", options="header"] +|=== +| Parameter | Description + +| `startPeriod` +| First period to include (`YYYY-MM`, inclusive) + +| `endPeriod` +| Last period to include (`YYYY-MM`, inclusive) -[source,json] +| `currency` +| Only include revenue in this currency, for example `USD` +|=== + +Each row contains the accounting period, the currency, the recognized amount, the deferred (not yet recognized) amount and the number of entries. + +=== Revenue by Plan + +Total, recognized and deferred amounts and the number of schedules for each plan, across the whole tenant. Takes no parameters. + +[source,bash] ---- -{ - "periods": ["2026-01", "2026-02", "2026-03", "2026-04", "2026-05", "2026-06"], - "rows": [ - { - "contractId": "ctr-001", - "contractName": "Acme Corp -- Enterprise", - "totalValue": 12000.00, - "recognized": [1000.00, 1000.00, 1000.00, 1000.00, 1000.00, 1000.00], - "deferred": 6000.00 - }, - { - "contractId": "ctr-002", - "contractName": "Beta Inc -- Standard", - "totalValue": 2400.00, - "recognized": [200.00, 200.00, 200.00, 200.00, 200.00, 200.00], - "deferred": 1200.00 - } - ], - "totals": { - "recognized": [1200.00, 1200.00, 1200.00, 1200.00, 1200.00, 1200.00], - "deferred": 7200.00 - } -} +curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/reports/by-plan" \ + -H "Authorization: Bearer ${ID_TOKEN}" \ + -H "X-Killbill-ApiKey: ${API_KEY}" \ + -H "X-Killbill-ApiSecret: ${API_SECRET}" ---- -This report is suitable for board-level financial reporting and can be exported for use in external accounting systems. +=== Recognition Rate -== Contract Revenue Allocation +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. -When contracts have multiple performance obligations, Aviate uses standalone selling prices (SSP) to allocate revenue per ASC 606. +[source,bash] +---- +curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/reports/recognition-rate" \ + -H "Authorization: Bearer ${ID_TOKEN}" \ + -H "X-Killbill-ApiKey: ${API_KEY}" \ + -H "X-Killbill-ApiSecret: ${API_SECRET}" +---- + +=== How Reports Are Calculated + +Reports are built from two different sources. Their figures can differ after cancellations, adjustments or credits. + +[cols="1,2,2", options="header"] +|=== +| Report | Built from | Currency handling -=== How Allocation Works +| Period summary +| Revenue entries in the period +| All currencies added together -Consider a contract with three components: +| Period currency summary +| Revenue entries in the period +| One row per currency -* Enterprise subscription: $10,000/year (SSP: $10,000) -* Implementation services: $3,000 one-time (SSP: $5,000) -* Premium support: $2,000/year (SSP: $2,000) -* *Total contract price*: $15,000 +| Revenue waterfall +| Revenue entries, by period +| One row per period and currency -Using relative SSP allocation: +| Revenue by plan +| Schedule totals +| All currencies added together -[cols="1,1,1,1", options="header"] +| Recognition rate +| Schedule totals, by recognition method +| All currencies added together |=== -| Obligation | SSP | SSP % | Allocated Revenue - -| Subscription -| $10,000 -| 58.8% -| $8,824 - -| Implementation -| $5,000 -| 29.4% -| $4,412 - -| Support -| $2,000 -| 11.8% -| $1,765 + +In entry-based reports, "deferred" is the total of entries *not yet recognized*. This includes entries left unrecognized after a cancellation or adjustment. + +== Viewing Revenue Details + +=== By Account, Subscription or Plan + +List revenue schedules with any combination of these filters: + +[cols="1,3", options="header"] |=== +| Parameter | Description -Note that the implementation fee ($3,000 charged) receives an allocation of $4,412 because the SSP-based allocation distributes the total contract price proportionally. This is the standard ASC 606 treatment for contracts where any individual obligation is discounted. +| `accountId` +| Schedules of one account -The allocation is computed once at contract inception and frozen -- subsequent changes to SSPs do not retroactively affect existing contracts. +| `subscriptionId` +| Schedules of one subscription -=== Setting Standalone Selling Prices +| `planName` +| Schedules for one plan -SSPs can be configured at the product offering level: +| `currency` +| Schedules in one currency + +| `closed` +| `true` for closed schedules, `false` for open ones + +| `servicePeriodStart` +| Schedules whose service period starts on or after this date (`YYYY-MM-DD`) + +| `offset`, `limit` +| Paging. `limit` defaults to and cannot exceed 1000. +|=== + +Results are returned newest first. [source,bash] ---- -curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/revenue/standalonePrices" \ +curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/schedules?accountId=${ACCOUNT_ID}&closed=false&limit=50" \ -H "Authorization: Bearer ${ID_TOKEN}" \ -H "X-Killbill-ApiKey: ${API_KEY}" \ - -H "X-Killbill-ApiSecret: ${API_SECRET}" \ - -H "Content-Type: application/json" \ - -d '{ - "productOfferingId": "po-impl", - "standaloneSellingPrice": 5000.00, - "currency": "USD", - "effectiveDate": "2026-01-01" - }' + -H "X-Killbill-ApiSecret: ${API_SECRET}" ---- -=== SSP Fallback Order - -If no explicit SSP is set, the system uses the following fallback order: +=== By Contract -. The configured standalone selling price for the product offering -. The list price of the product offering (from the pricing tower) -. The contract line item price (as a last resort) +List the revenue schedules of a contract's subscriptions: -We recommend setting explicit SSPs for all product offerings to ensure consistent and auditable allocations. +[source,bash] +---- +curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/contracts/${CONTRACT_ID}/schedules" \ + -H "Authorization: Bearer ${ID_TOKEN}" \ + -H "X-Killbill-ApiKey: ${API_KEY}" \ + -H "X-Killbill-ApiSecret: ${API_SECRET}" +---- -== Viewing Revenue Details +=== By Invoice Item or Schedule -=== By Account +Get the schedule of an invoice item, using its Kill Bill invoice item ID: [source,bash] ---- -curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/accounts/a1b2c3d4-..." \ +curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/${INVOICE_ITEM_ID}/schedule" \ -H "Authorization: Bearer ${ID_TOKEN}" \ -H "X-Killbill-ApiKey: ${API_KEY}" \ -H "X-Killbill-ApiSecret: ${API_SECRET}" ---- -=== By Contract +Get a schedule by its ID. Schedule IDs are numbers and are returned in the schedule details. [source,bash] ---- -curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/contracts/ctr-001" \ +curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/schedules/${SCHEDULE_ID}" \ -H "Authorization: Bearer ${ID_TOKEN}" \ -H "X-Killbill-ApiKey: ${API_KEY}" \ -H "X-Killbill-ApiSecret: ${API_SECRET}" ---- -Response: - -[source,json] ----- -{ - "contractId": "ctr-001", - "totalValue": 15000.00, - "totalRecognized": 8823.53, - "totalDeferred": 6176.47, - "obligations": [ - { - "name": "Enterprise Subscription", - "allocatedRevenue": 8824.00, - "recognized": 5149.33, - "deferred": 3674.67, - "recognitionPattern": "STRAIGHT_LINE", - "termMonths": 12 - }, - { - "name": "Implementation Services", - "allocatedRevenue": 4412.00, - "recognized": 4412.00, - "deferred": 0.00, - "recognitionPattern": "POINT_IN_TIME" - } - ] -} +List the revenue entries of a schedule, showing each entry's date, amount, accounting period and whether it has been recognized: + +[source,bash] +---- +curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/${SCHEDULE_ID}/entriesPerSchedule" \ + -H "Authorization: Bearer ${ID_TOKEN}" \ + -H "X-Killbill-ApiKey: ${API_KEY}" \ + -H "X-Killbill-ApiSecret: ${API_SECRET}" ---- + +[[revrec-business-rules]] +== Business Rules and Constraints + +=== Recognition + +* Recognition follows the service dates on the invoice item, not the invoice date or the payment date. Revenue is recognized whether or not the invoice has been paid. +* Revenue is always assigned to calendar months. Custom fiscal calendars (for example 4-4-5 periods) are not supported. + +=== Closed Periods + +* Closing a period does not block billing. Kill Bill still accepts invoices, credits, adjustments and payments dated in a closed period. +* If a new invoice item has service dates in a closed period, Aviate does not create its revenue entries. If you expect back-dated invoices, reopen the affected period *before* the invoice is generated. +* Adjustments and credits processed after a period is closed still update the affected schedules. + +[[revrec-cancellations]] +=== Cancellations and Adjustments + +When an invoice item is reduced after its schedule exists, for example by an item adjustment or by the credit Kill Bill issues when a subscription is cancelled or changed mid-period: + +* If the item still has deferred revenue, Aviate records a *reversal entry* for the adjustment amount, ends the schedule at the adjustment date and closes it. Days after that date are not recognized. +* If the item's revenue has already been fully recognized, the schedule is not changed and no reversal is recorded. +* The days that were not recognized remain in their month as unrecognized entries. Closing a month that contains a mid-period cancellation or adjustment therefore requires `force=true`. +* Reversal entries are not assigned to an accounting period, so they do not appear in period summaries or in a waterfall that has a start period. + +=== Account Credits + +* A credit created on its own, outside an invoice that also contains charges, reduces the deferred revenue of the account's open schedules. You cannot choose which schedules a credit is applied to. +* Credits that appear on the same invoice as recurring, usage, fixed or external charges are not treated as revenue adjustments and do not change any schedule. + +=== Data You Cannot Edit + +Revenue schedules and entries are derived from invoices. You cannot create, edit or delete them directly. To change revenue, change the underlying invoice, for example with an item adjustment. + +== Examples + +=== Monthly Subscription + +A customer is invoiced *$31.00* for a monthly plan covering `2026-01-01` to `2026-02-01`. + +* Aviate creates a straight-line schedule with a total of $31.00, all deferred. +* The service period is 31 days, so Aviate creates 31 entries of $1.00, dated `2026-01-01` to `2026-01-31`, all in period `2026-01`. +* After the run on `2026-01-10`, $10.00 is recognized and $21.00 is deferred. +* After the run on `2026-01-31`, the full $31.00 is recognized and the schedule is closed. + +=== Quarterly Subscription Spanning Three Months + +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: + +[cols="1,1,1", options="header"] +|=== +| Period | Days | Revenue + +| `2026-01` +| 31 +| $31.00 + +| `2026-02` +| 28 +| $28.00 + +| `2026-03` +| 31 +| $31.00 + +| *Total* +| *90* +| *$90.00* +|=== + +At the end of January, $31.00 is recognized and $59.00 is still deferred. + +=== Rounding + +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. + +=== One-Time Setup Fee + +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. + +=== Month-End Close + +On `2026-05-02`, the finance team closes April: + +. The daily run on `2026-04-30` or later has recognized all April entries. +. `GET /v1/revenue/periods/2026-04/summary` shows the recognized total for April with a deferred amount of 0. +. `POST /v1/revenue/periods/2026-04/close` returns `204 No Content`. +. `GET /v1/revenue/periods?closed=true` now lists `2026-04` with the closing date and user. + +If a subscription had been cancelled in the middle of April, its remaining April days would still be unrecognized. Step 3 would then be rejected with `Cannot close period 2026-04: N unrecognized entries remain`, and after review the team would close the month with `force=true`. + +=== Mid-Period Cancellation + +A $31.00 schedule covers `2026-01-01` to `2026-02-01`. By `2026-01-15`, $15.00 has been recognized. The subscription is then cancelled with effect from `2026-01-16`, and Kill Bill credits the unused $16.00. + +* Aviate records a reversal entry of −$16.00, ends the schedule on `2026-01-16` and closes it. +* Days after `2026-01-16` are not recognized. +* The unrecognized January days stay in period `2026-01`, so closing January requires `force=true`. +* The reversal entry has no accounting period, so it does not appear in the January period summary. From 0afda560c4b906b636bb6b2fc04dc9d8c173a9ba Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:26:00 +0530 Subject: [PATCH 2/5] Include Max's changes --- .../accounting-periods.png | Bin 0 -> 120187 bytes .../revenue-recognition/recognition-rates.png | Bin 0 -> 166874 bytes .../aviate-revenue-recognition-v2.adoc | 454 +++++ .../aviate-revenue-recognition-v2.html | 1501 ++++++++++++++++ .../preview/aviate-revenue-recognition.adoc | 281 ++- .../tutorials/email-notification-plugin.html | 1594 +++++++++++++++++ 6 files changed, 3787 insertions(+), 43 deletions(-) create mode 100644 userguide/assets/img/aviate/revenue-recognition/accounting-periods.png create mode 100644 userguide/assets/img/aviate/revenue-recognition/recognition-rates.png create mode 100644 userguide/preview/aviate-revenue-recognition-v2.adoc create mode 100644 userguide/preview/aviate-revenue-recognition-v2.html create mode 100644 userguide/tutorials/email-notification-plugin.html diff --git a/userguide/assets/img/aviate/revenue-recognition/accounting-periods.png b/userguide/assets/img/aviate/revenue-recognition/accounting-periods.png new file mode 100644 index 0000000000000000000000000000000000000000..b7400c2e2fd2d3098b55b4668565feabf7d53b1d GIT binary patch literal 120187 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 z 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

Meg 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­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 **Note:** The module calculates and reports revenue from billing data. It does not post entries to a general ledger and does not export journals. Whether its output meets a particular accounting standard is for your finance team to determine. + +## Key Features + +| Feature | Description | +|---------|-------------| +| Automatic revenue schedules | A schedule is created for every eligible invoice item when the invoice is generated. No manual setup is required. | +| Two recognition methods | **Straight-line** (daily) for recurring and usage charges; **immediate** for fixed (one-time) and external charges. | +| Daily recognition | A background process recognizes all entries whose date has been reached. By default it runs once a day. | +| Monthly accounting periods | Periods named `YYYY-MM` are created automatically as revenue entries are generated. You can also create periods yourself. | +| Period close and reopen | Close a month once all of its revenue has been recognized; reopen it if you need to. | +| Adjustment handling | Invoice item adjustments, cancellation credits and standalone account credits are reflected in the affected schedules. | +| Schedule lookup | Look up schedules by invoice item or schedule ID, or list them with filters such as account, subscription, plan, currency and status. | +| Revenue reports | Period summary, per-currency period summary, revenue waterfall, revenue by plan and recognition rate. | + +### Before you begin + +Revenue recognition is **disabled by default**. Your Aviate administrator enables it in the plugin configuration: + +| Property | Default | Description | +|----------|---------|-------------| +| `com.killbill.billing.plugin.aviate.enableRevenueRecognition` | `false` | Set to `true` to create revenue schedules for new invoices and to start the daily recognition process. | +| `com.killbill.billing.plugin.aviate.revenueRecognition.delaySeconds` | `86400` (one day) | How often the recognition process runs, in seconds. | + +Revenue schedules are created as invoices are generated. Enable the feature before you start billing the customers whose revenue you want to track. + +## Accounting Periods + +An accounting period groups revenue entries by calendar month. Periods are identified by name, in the format `YYYY-MM` (for example `2026-04`). + +### How periods are created + +- **Automatically.** When Aviate creates revenue entries for an invoice item, it creates any monthly period that does not already exist, from the first to the last day of that month. +- **Manually.** You can create a period ahead of time by giving it a name, a start date and an end date. + +Every revenue entry is assigned to the period named after the month of its date. For example, an entry dated `2026-04-17` belongs to period `2026-04`. When you create a period manually, use the same `YYYY-MM` name with the first and last day of the month. A period with any other name receives no revenue entries. + +### Supported operations + +| Operation | What it does | +|-----------|--------------| +| Create | Creates a period with a name, start date and end date. The name must be unique, and the end date cannot be before the start date. | +| List | Lists all periods. Can be filtered to only open or only closed periods. | +| View | Shows one period: its dates, whether it is closed, and when and by whom it was closed. | +| Close | Closes an open period. Rejected if the period still contains unrecognized revenue entries, unless you force the close. | +| Reopen | Reopens a closed period. Its unrecognized entries become eligible for recognition again. | +| Summary | Shows recognized and deferred revenue and the number of entries in the period, for all currencies combined or per currency. | + +### Closing a period + +To close a period: + +- The period must exist and must not already be closed. +- All revenue entries dated in that period must already be recognized. Otherwise the close is rejected with a message like `Cannot close period 2026-04: 12 unrecognized entries remain`. +- You can override this check with the `force` option. Use it when you have reviewed the remaining entries and still want to close the month. For a common case where this is needed, see [Cancellations and adjustments](#cancellations-and-adjustments). + +When a period is closed: + +- The date and the user who closed it are recorded. +- The daily recognition process no longer recognizes any remaining unrecognized entries in that period. +- Aviate does not create revenue entries for new invoice items whose service dates fall in that period (see [Closed periods](#closed-periods)). + +### Reopening a period + +Only a closed period can be reopened. 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. + +## Revenue Recognition Process + +### 1. Schedule creation (when an invoice is generated) + +When Kill Bill generates an invoice, Aviate examines each invoice item and creates one revenue schedule per eligible item: + +| Invoice item type | Recognition method | How the amount is spread | +|-------------------|--------------------|--------------------------| +| Recurring | Straight-line | Evenly, one entry per day of the service period | +| Usage | Straight-line | Evenly, one entry per day of the service period | +| Fixed (one-time) | Immediate | One entry for the full amount on the service start date | +| External charge | Immediate | One entry for the full amount on the service start date | + +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. + +Each schedule records: + +- The invoice, invoice item, account, subscription, plan and phase it came from. +- Its currency and total amount. +- Its service period and recognition method. +- Its running **recognized** and **deferred** amounts. At creation, the full amount is deferred. +- Whether it is closed, meaning fully recognized or ended early by an adjustment. + +### 2. Straight-line calculation + +For straight-line schedules: + +- The service period runs from the item's start date up to, but **not including**, its end date. A 1 January to 1 February period is 31 days. +- The daily amount is the total divided by the number of days, rounded to nine decimal places. +- The last day takes any rounding difference, so the entries always add up exactly to the schedule total. + +### 3. Daily recognition + +A background process runs at the configured interval, once a day by default. Each run: + +- Recognizes every unrecognized entry dated **on or before the current date (UTC)** in an open period, including entries dated today. +- Updates each affected schedule's recognized and deferred amounts. +- Closes a schedule once its full amount has been recognized. + +### Recognizing revenue for a specific month + +There is no customer-facing operation that runs recognition on demand for a chosen date or month. Revenue for a month is recognized by the regular runs as its days pass. All of a month's entries have been processed once a run has taken place on or after the last day of that month. + +The month-end workflow is: + +1. Wait for a recognition run on or after the last day of the month. +2. Review the month with the period summary. +3. Close the period. + +See [Close a month](#close-a-month) for the steps. + +## Business Rules and Constraints + +### Recognition rules + +- The recognition method depends only on the invoice item type. It cannot be configured per plan, product or customer. +- Recognition follows the service dates on the invoice item, not the invoice date or the payment date. Revenue is recognized whether or not the invoice has been paid. +- Revenue is always assigned to calendar months. Custom fiscal calendars (for example 4-4-5 periods) are not supported. + +### Closed periods + +- Closing a period **does not block billing**. Invoices, credits, adjustments and payments dated in a closed period are still accepted by Kill Bill. +- If a new invoice item has service dates in a closed period, Aviate does not create its revenue entries. If you expect back-dated invoices, reopen the affected period **before** the invoice is generated. +- Adjustments and credits processed after a period is closed still update the affected schedules (see below). + +### Cancellations and adjustments + +When an invoice item is reduced after its schedule exists, for example by an item adjustment or by the credit Kill Bill issues when a subscription is cancelled or changed mid-period: + +- If the item still has deferred revenue, Aviate records a **reversal entry** for the adjustment amount, ends the schedule at the adjustment date and closes it. Days after that date are not recognized. +- If the item's revenue has already been fully recognized, the schedule is not changed and no reversal is recorded. +- The days that were not recognized remain in their month as unrecognized entries. **Closing a month that contains a mid-period cancellation or adjustment therefore requires the `force` option.** +- Reversal entries are not assigned to an accounting period, so they do not appear in period summaries or in a waterfall that has a start period. + +### Account credits + +- A credit created on its own, outside an invoice that also contains charges, reduces the deferred revenue of the account's open schedules. You cannot choose which schedules a credit is applied to. +- Credits that appear on the same invoice as recurring, usage, fixed or external charges are not treated as revenue adjustments and do not change any schedule. + +### Reports + +Reports are built from two different sources. Their figures can differ after cancellations, adjustments or credits. + +| Report | Built from | Currency handling | +|--------|-----------|-------------------| +| Period summary | Revenue entries in the period | All currencies added together | +| Period currency summary | Revenue entries in the period | One row per currency | +| Revenue waterfall | Revenue entries, by period | One row per period and currency | +| Revenue by plan | Schedule totals | All currencies added together | +| Recognition rate | Schedule totals, by recognition method | All currencies added together | + +- In entry-based reports, "deferred" is the total of entries **not yet recognized**. This includes entries left unrecognized after a cancellation or adjustment. +- For tenants that bill in more than one currency, use the period currency summary or the waterfall to avoid adding amounts in different currencies together. + +### Access and permissions + +- All revenue operations apply to the tenant identified by the Kill Bill API key and secret on the request. +- When role-based access control is enabled in Aviate, any authenticated role can read revenue data. Creating, closing and reopening periods requires one of the roles `finance_admin`, `finance_vp`, `system_admin`, `admin` or `super_admin`. + +### Data you cannot edit + +Revenue schedules and entries are derived from invoices. You cannot create, edit or delete them directly. To change revenue, change the underlying invoice, for example with an item adjustment. + +## Usage Instructions + +All operations are available through the Aviate REST API under: + +``` +http://:8080/plugins/aviate-plugin/v1/revenue +``` + +Every request needs: + +- `Authorization: Bearer ${ID_TOKEN}` (your Aviate token) +- `X-killbill-apiKey` and `X-killbill-apisecret` (your tenant credentials) + +Parameters are passed in the query string. As with other Aviate actions, send `POST` requests with `Content-Type: application/json` and an empty JSON body (`{}`). + +The examples below use these shell variables: + +``` +export AVIATE=http://127.0.0.1:8080/plugins/aviate-plugin +export API_KEY= +export API_SECRET= +``` + +### Look up revenue schedules + +**List schedules** with any combination of filters: + +| Query parameter | Description | +|-----------------|-------------| +| `accountId` | Schedules of one account | +| `subscriptionId` | Schedules of one subscription | +| `planName` | Schedules for one plan | +| `currency` | Schedules in one currency, for example `USD` | +| `closed` | `true` for closed schedules, `false` for open ones | +| `servicePeriodStart` | Schedules whose service period starts on or after this date (`YYYY-MM-DD`) | +| `offset`, `limit` | Paging. `limit` defaults to and cannot exceed 1000. | + +Results are returned newest first. + +``` +curl -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + "${AVIATE}/v1/revenue/schedules?accountId=${ACCOUNT_ID}&closed=false&limit=50" | jq . +``` + +**Get the schedule of an invoice item**, using the Kill Bill invoice item ID: + +``` +curl -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + "${AVIATE}/v1/revenue/${INVOICE_ITEM_ID}/schedule" | jq . +``` + +**Get a schedule by its ID.** Schedule IDs are numbers and are returned in the schedule details. + +``` +curl -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + "${AVIATE}/v1/revenue/schedules/${SCHEDULE_ID}" | jq . +``` + +**List the revenue entries of a schedule**, showing each entry's date, amount, period and whether it has been recognized: + +``` +curl -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + "${AVIATE}/v1/revenue/${SCHEDULE_ID}/entriesPerSchedule" | jq . +``` + +### Manage accounting periods + +**Create a period.** All three parameters are required. A successful request returns `201 Created`. + +``` +curl -X POST \ + -H'Content-Type: application/json' \ + -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + -d '{}' \ + "${AVIATE}/v1/revenue/periods?periodName=2026-05&startDate=2026-05-01&endDate=2026-05-31" +``` + +**List periods.** Add `closed=true` or `closed=false` to filter. + +``` +curl -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + "${AVIATE}/v1/revenue/periods?closed=false" | jq . +``` + +**View one period:** + +``` +curl -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + "${AVIATE}/v1/revenue/periods/2026-04" | jq . +``` + +### Close a month + +1. **Check that the month has been processed.** A recognition run must have taken place on or after the last day of the month. + +2. **Review the period summary.** It returns the period name, the recognized amount, the deferred (not yet recognized) amount and the number of entries. + + ``` + curl -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + "${AVIATE}/v1/revenue/periods/2026-04/summary" | jq . + ``` + + For figures per currency, use `currencySummary` instead: + + ``` + curl -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + "${AVIATE}/v1/revenue/periods/2026-04/currencySummary" | jq . + ``` + +3. **Close the period.** A successful close returns `204 No Content`. + + ``` + curl -X POST \ + -H'Content-Type: application/json' \ + -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + -d '{}' \ + "${AVIATE}/v1/revenue/periods/2026-04/close" + ``` + +4. **If the close is rejected because unrecognized entries remain,** look at the schedules involved (for example, those closed early by a cancellation). If you still want to close the month, repeat the request with `force=true`: + + ``` + curl -X POST \ + -H'Content-Type: application/json' \ + -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + -d '{}' \ + "${AVIATE}/v1/revenue/periods/2026-04/close?force=true" + ``` + +### Reopen a month + +A successful reopen returns `204 No Content`. The request is rejected if the period does not exist or is not closed. + +``` +curl -X POST \ + -H'Content-Type: application/json' \ + -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + -d '{}' \ + "${AVIATE}/v1/revenue/periods/2026-04/reopen" +``` + +### Run reports + +**Revenue waterfall.** Recognized and deferred revenue per period and currency. All parameters are optional: `startPeriod` and `endPeriod` (`YYYY-MM`, inclusive) and `currency`. + +``` +curl -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + "${AVIATE}/v1/revenue/reports/waterfall?startPeriod=2026-01&endPeriod=2026-06¤cy=USD" | jq . +``` + +**Revenue by plan.** Total, recognized and deferred amounts and the number of schedules per plan, across the whole tenant. Takes no parameters. + +``` +curl -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + "${AVIATE}/v1/revenue/reports/by-plan" | jq . +``` + +**Recognition rate.** 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. + +``` +curl -H"Authorization: Bearer ${ID_TOKEN}" \ + -H"X-killbill-apiKey: ${API_KEY}" \ + -H"X-killbill-apisecret: ${API_SECRET}" \ + "${AVIATE}/v1/revenue/reports/recognition-rate" | jq . +``` + +## Examples + +### Example 1: Monthly subscription + +A customer is invoiced **USD 31.00** for a monthly plan covering `2026-01-01` to `2026-02-01`. + +- Aviate creates a straight-line schedule with a total of 31.00, all deferred. +- The service period is 31 days, so Aviate creates 31 entries of 1.00, dated `2026-01-01` to `2026-01-31`, all in period `2026-01`. +- Each daily run recognizes the entries dated up to that day. After the run on `2026-01-10`, 10.00 is recognized and 21.00 is deferred. +- After the run on `2026-01-31`, the full 31.00 is recognized and the schedule is closed. + +### Example 2: Quarterly subscription spanning three months + +A customer is invoiced **USD 90.00** for a quarterly plan covering `2026-01-01` to `2026-04-01`, which is 90 days. The daily amount is 1.00, so the revenue falls into three periods: + +| Period | Days | Revenue | +|--------|------|---------| +| `2026-01` | 31 | 31.00 | +| `2026-02` | 28 | 28.00 | +| `2026-03` | 31 | 31.00 | +| **Total** | **90** | **90.00** | + +At the end of January, 31.00 is recognized and 59.00 is still deferred. + +### Example 3: Rounding + +A customer is invoiced **USD 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. + +### Example 4: One-time setup fee + +A customer is invoiced a fixed **USD 250.00** setup fee with a service start date of `2026-04-15`. + +- Aviate creates an immediate schedule with one entry of 250.00 dated `2026-04-15`, in period `2026-04`. +- The first recognition run on or after `2026-04-15` recognizes the full amount and closes the schedule. + +### Example 5: Month-end close + +On `2026-05-02`, the finance team closes April: + +1. The daily run on `2026-04-30` or later has recognized all April entries. +2. `GET /v1/revenue/periods/2026-04/summary` shows the recognized total for April with a deferred amount of 0. +3. `POST /v1/revenue/periods/2026-04/close` returns `204 No Content`. +4. `GET /v1/revenue/periods?closed=true` now lists `2026-04` with the closing date and user. + +If a subscription had been cancelled in the middle of April, its remaining April days would still be unrecognized. Step 3 would be rejected with `Cannot close period 2026-04: N unrecognized entries remain`. After review, the team would close the month with `force=true`. + +### Example 6: Mid-period cancellation + +A USD 31.00 schedule covers `2026-01-01` to `2026-02-01`. By `2026-01-15`, 15.00 has been recognized. The subscription is then cancelled with effect from `2026-01-16`, and Kill Bill credits the unused 16.00. + +- Aviate records a reversal entry of −16.00, ends the schedule on `2026-01-16` and closes it. +- Days after `2026-01-16` are not recognized. +- The unrecognized January days stay in period `2026-01`. Closing January therefore requires `force=true`. +- The reversal entry has no accounting period, so it does not appear in the January period summary. diff --git a/userguide/preview/aviate-revenue-recognition-v2.html b/userguide/preview/aviate-revenue-recognition-v2.html new file mode 100644 index 000000000..79588891d --- /dev/null +++ b/userguide/preview/aviate-revenue-recognition-v2.html @@ -0,0 +1,1501 @@ + + + + + + + +Revenue Recognition + + + + + +

+
+
+
+
+

The Aviate Revenue Recognition module turns the invoices that Kill Bill produces into revenue schedules. It spreads each invoiced amount over the period in which the service is delivered and tracks, day by day, how much of that amount has been recognized as revenue and how much is still deferred. Finance teams use it to see deferred and recognized revenue per accounting month, and to close and reopen those months.

+
+
+

This guide describes the functionality that is available today, the rules it follows, and how to use it through the Aviate API.

+
+
+
+
+

Table of Contents

+
+
+
    +
  • +

    [Overview](#overview)

    +
    • +
  • +

    [Key Features](#key-features)

    +
    • +
  • +

    [Accounting Periods](#accounting-periods)

    +
    • +
  • +

    [Revenue Recognition Process](#revenue-recognition-process)

    +
    • +
  • +

    [Business Rules and Constraints](#business-rules-and-constraints)

    +
    • +
  • +

    [Usage Instructions](#usage-instructions)

    +
    • +
  • +

    [Examples](#examples)

    +
    • +
+
+
+
+
+

Overview

+
+
+

When you bill a customer in advance, for example a monthly or annual subscription, the cash and the invoice arrive before the service is delivered. Accounting practice generally treats that amount as deferred revenue that becomes recognized revenue over the service period.

+
+
+

The Revenue Recognition module automates this for invoices generated by Kill Bill:

+
+
+
    +
  • +

    It creates a revenue schedule for each eligible invoice item as soon as the invoice is generated.

    +
    • +
  • +

    It splits the schedule into dated revenue entries, either one per day of the service period or a single entry for one-time charges.

    +
    • +
  • +

    A background process marks entries as recognized once their date is reached.

    +
    • +
  • +

    Every entry belongs to an accounting period (a calendar month), which you can close at month-end and reopen if needed.

    +
    • +
  • +

    Reports show recognized and deferred revenue by period, by currency, by plan and by recognition method.

    +
    • +
+
+
+

The module answers questions such as:

+
+
+
    +
  • +

    How much of what we invoiced has been earned so far, and how much is still deferred?

    +
    • +
  • +

    How much revenue was recognized in March?

    +
    • +
  • +

    Which schedules does a given account or subscription have, and where does each one stand?

    +
    • +
+
+
+
+
+

Note: The module calculates and reports revenue from billing data. It does not post entries to a general ledger and does not export journals. Whether its output meets a particular accounting standard is for your finance team to determine.

+
+
+
+
+
+
+

Key Features

+
+
+

| Feature | Description | +|---------|-------------| +| Automatic revenue schedules | A schedule is created for every eligible invoice item when the invoice is generated. No manual setup is required. | +| Two recognition methods | Straight-line (daily) for recurring and usage charges; immediate for fixed (one-time) and external charges. | +| Daily recognition | A background process recognizes all entries whose date has been reached. By default it runs once a day. | +| Monthly accounting periods | Periods named YYYY-MM are created automatically as revenue entries are generated. You can also create periods yourself. | +| Period close and reopen | Close a month once all of its revenue has been recognized; reopen it if you need to. | +| Adjustment handling | Invoice item adjustments, cancellation credits and standalone account credits are reflected in the affected schedules. | +| Schedule lookup | Look up schedules by invoice item or schedule ID, or list them with filters such as account, subscription, plan, currency and status. | +| Revenue reports | Period summary, per-currency period summary, revenue waterfall, revenue by plan and recognition rate. |

+
+
+

Before you begin

+
+

Revenue recognition is disabled by default. Your Aviate administrator enables it in the plugin configuration:

+
+
+

| Property | Default | Description | +|----------|---------|-------------| +| com.killbill.billing.plugin.aviate.enableRevenueRecognition | false | Set to true to create revenue schedules for new invoices and to start the daily recognition process. | +| com.killbill.billing.plugin.aviate.revenueRecognition.delaySeconds | 86400 (one day) | How often the recognition process runs, in seconds. |

+
+
+

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

+
+
+
+
+
+

Accounting Periods

+
+
+

An accounting period groups revenue entries by calendar month. Periods are identified by name, in the format YYYY-MM (for example 2026-04).

+
+
+

How periods are created

+
+
    +
  • +

    Automatically. When Aviate creates revenue entries for an invoice item, it creates any monthly period that does not already exist, from the first to the last day of that month.

    +
    • +
  • +

    Manually. You can create a period ahead of time by giving it a name, a start date and an end date.

    +
    • +
+
+
+

Every revenue entry is assigned to the period named after the month of its date. For example, an entry dated 2026-04-17 belongs to period 2026-04. When you create a period manually, use the same YYYY-MM name with the first and last day of the month. A period with any other name receives no revenue entries.

+
+
+
+

Supported operations

+
+

| Operation | What it does | +|-----------|--------------| +| Create | Creates a period with a name, start date and end date. The name must be unique, and the end date cannot be before the start date. | +| List | Lists all periods. Can be filtered to only open or only closed periods. | +| View | Shows one period: its dates, whether it is closed, and when and by whom it was closed. | +| Close | Closes an open period. Rejected if the period still contains unrecognized revenue entries, unless you force the close. | +| Reopen | Reopens a closed period. Its unrecognized entries become eligible for recognition again. | +| Summary | Shows recognized and deferred revenue and the number of entries in the period, for all currencies combined or per currency. |

+
+
+
+

Closing a period

+
+

To close a period:

+
+
+
    +
  • +

    The period must exist and must not already be closed.

    +
    • +
  • +

    All revenue entries dated in that period must already be recognized. Otherwise the close is rejected with a message like Cannot close period 2026-04: 12 unrecognized entries remain.

    +
    • +
  • +

    You can override this check with the force option. Use it when you have reviewed the remaining entries and still want to close the month. For a common case where this is needed, see [Cancellations and adjustments](#cancellations-and-adjustments).

    +
    • +
+
+
+

When a period is closed:

+
+
+
    +
  • +

    The date and the user who closed it are recorded.

    +
    • +
  • +

    The daily recognition process no longer recognizes any remaining unrecognized entries in that period.

    +
    • +
  • +

    Aviate does not create revenue entries for new invoice items whose service dates fall in that period (see [Closed periods](#closed-periods)).

    +
    • +
+
+
+
+

Reopening a period

+
+

Only a closed period can be reopened. 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.

+
+
+
+
+
+

Revenue Recognition Process

+
+
+

1. Schedule creation (when an invoice is generated)

+
+

When Kill Bill generates an invoice, Aviate examines each invoice item and creates one revenue schedule per eligible item:

+
+
+

| Invoice item type | Recognition method | How the amount is spread | +|-------------------|--------------------|--------------------------| +| Recurring | Straight-line | Evenly, one entry per day of the service period | +| Usage | Straight-line | Evenly, one entry per day of the service period | +| Fixed (one-time) | Immediate | One entry for the full amount on the service start date | +| External charge | Immediate | One entry for the full amount on the service start date |

+
+
+

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.

+
+
+

Each schedule records:

+
+
+
    +
  • +

    The invoice, invoice item, account, subscription, plan and phase it came from.

    +
    • +
  • +

    Its currency and total amount.

    +
    • +
  • +

    Its service period and recognition method.

    +
    • +
  • +

    Its running recognized and deferred amounts. At creation, the full amount is deferred.

    +
    • +
  • +

    Whether it is closed, meaning fully recognized or ended early by an adjustment.

    +
    • +
+
+
+
+

2. Straight-line calculation

+
+

For straight-line schedules:

+
+
+
    +
  • +

    The service period runs from the item’s start date up to, but not including, its end date. A 1 January to 1 February period is 31 days.

    +
    • +
  • +

    The daily amount is the total divided by the number of days, rounded to nine decimal places.

    +
    • +
  • +

    The last day takes any rounding difference, so the entries always add up exactly to the schedule total.

    +
    • +
+
+
+
+

3. Daily recognition

+
+

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

+
+
+
    +
  • +

    Recognizes every unrecognized entry dated on or before the current date (UTC) in an open period, including entries dated today.

    +
    • +
  • +

    Updates each affected schedule’s recognized and deferred amounts.

    +
    • +
  • +

    Closes a schedule once its full amount has been recognized.

    +
    • +
+
+
+
+

Recognizing revenue for a specific month

+
+

There is no customer-facing operation that runs recognition on demand for a chosen date or month. Revenue for a month is recognized by the regular runs as its days pass. All of a month’s entries have been processed once a run has taken place on or after the last day of that month.

+
+
+

The month-end workflow is:

+
+
+
    +
  1. +

    Wait for a recognition run on or after the last day of the month.

    +
    2. +
  2. +

    Review the month with the period summary.

    +
    3. +
  3. +

    Close the period.

    +
    4. +
+
+
+

See [Close a month](#close-a-month) for the steps.

+
+
+
+
+
+

Business Rules and Constraints

+
+
+

Recognition rules

+
+
    +
  • +

    The recognition method depends only on the invoice item type. It cannot be configured per plan, product or customer.

    +
    • +
  • +

    Recognition follows the service dates on the invoice item, not the invoice date or the payment date. Revenue is recognized whether or not the invoice has been paid.

    +
    • +
  • +

    Revenue is always assigned to calendar months. Custom fiscal calendars (for example 4-4-5 periods) are not supported.

    +
    • +
+
+
+
+

Closed periods

+
+
    +
  • +

    Closing a period does not block billing. Invoices, credits, adjustments and payments dated in a closed period are still accepted by Kill Bill.

    +
    • +
  • +

    If a new invoice item has service dates in a closed period, Aviate does not create its revenue entries. If you expect back-dated invoices, reopen the affected period before the invoice is generated.

    +
    • +
  • +

    Adjustments and credits processed after a period is closed still update the affected schedules (see below).

    +
    • +
+
+
+
+

Cancellations and adjustments

+
+

When an invoice item is reduced after its schedule exists, for example by an item adjustment or by the credit Kill Bill issues when a subscription is cancelled or changed mid-period:

+
+
+
    +
  • +

    If the item still has deferred revenue, Aviate records a reversal entry for the adjustment amount, ends the schedule at the adjustment date and closes it. Days after that date are not recognized.

    +
    • +
  • +

    If the item’s revenue has already been fully recognized, the schedule is not changed and no reversal is recorded.

    +
    • +
  • +

    The days that were not recognized remain in their month as unrecognized entries. Closing a month that contains a mid-period cancellation or adjustment therefore requires the force option.

    +
    • +
  • +

    Reversal entries are not assigned to an accounting period, so they do not appear in period summaries or in a waterfall that has a start period.

    +
    • +
+
+
+
+

Account credits

+
+
    +
  • +

    A credit created on its own, outside an invoice that also contains charges, reduces the deferred revenue of the account’s open schedules. You cannot choose which schedules a credit is applied to.

    +
    • +
  • +

    Credits that appear on the same invoice as recurring, usage, fixed or external charges are not treated as revenue adjustments and do not change any schedule.

    +
    • +
+
+
+
+

Reports

+
+

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

+
+
+

| Report | Built from | Currency handling | +|--------|-----------|-------------------| +| Period summary | Revenue entries in the period | All currencies added together | +| Period currency summary | Revenue entries in the period | One row per currency | +| Revenue waterfall | Revenue entries, by period | One row per period and currency | +| Revenue by plan | Schedule totals | All currencies added together | +| Recognition rate | Schedule totals, by recognition method | All currencies added together |

+
+
+
    +
  • +

    In entry-based reports, "deferred" is the total of entries not yet recognized. This includes entries left unrecognized after a cancellation or adjustment.

    +
    • +
  • +

    For tenants that bill in more than one currency, use the period currency summary or the waterfall to avoid adding amounts in different currencies together.

    +
    • +
+
+
+
+

Access and permissions

+
+
    +
  • +

    All revenue operations apply to the tenant identified by the Kill Bill API key and secret on the request.

    +
    • +
  • +

    When role-based access control is enabled in Aviate, any authenticated role can read revenue data. Creating, closing and reopening periods requires one of the roles finance_admin, finance_vp, system_admin, admin or super_admin.

    +
    • +
+
+
+
+

Data you cannot edit

+
+

Revenue schedules and entries are derived from invoices. You cannot create, edit or delete them directly. To change revenue, change the underlying invoice, for example with an item adjustment.

+
+
+
+
+
+

Usage Instructions

+
+
+

All operations are available through the Aviate REST API under:

+
+
+
+
http://<killbill-host>:8080/plugins/aviate-plugin/v1/revenue
+
+
+
+

Every request needs:

+
+
+
    +
  • +

    Authorization: Bearer ${ID_TOKEN} (your Aviate token)

    +
    • +
  • +

    X-killbill-apiKey and X-killbill-apisecret (your tenant credentials)

    +
    • +
+
+
+

Parameters are passed in the query string. As with other Aviate actions, send POST requests with Content-Type: application/json and an empty JSON body ({}).

+
+
+

The examples below use these shell variables:

+
+
+
+
export AVIATE=http://127.0.0.1:8080/plugins/aviate-plugin
+export API_KEY=<your-api-key>
+export API_SECRET=<your-api-secret>
+
+
+
+

Look up revenue schedules

+
+

List schedules with any combination of filters:

+
+
+

| Query parameter | Description | +|-----------------|-------------| +| accountId | Schedules of one account | +| subscriptionId | Schedules of one subscription | +| planName | Schedules for one plan | +| currency | Schedules in one currency, for example USD | +| closed | true for closed schedules, false for open ones | +| servicePeriodStart | Schedules whose service period starts on or after this date (YYYY-MM-DD) | +| offset, limit | Paging. limit defaults to and cannot exceed 1000. |

+
+
+

Results are returned newest first.

+
+
+
+
curl -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     "${AVIATE}/v1/revenue/schedules?accountId=${ACCOUNT_ID}&closed=false&limit=50" | jq .
+
+
+
+

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

+
+
+
+
curl -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     "${AVIATE}/v1/revenue/${INVOICE_ITEM_ID}/schedule" | jq .
+
+
+
+

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

+
+
+
+
curl -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     "${AVIATE}/v1/revenue/schedules/${SCHEDULE_ID}" | jq .
+
+
+
+

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

+
+
+
+
curl -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     "${AVIATE}/v1/revenue/${SCHEDULE_ID}/entriesPerSchedule" | jq .
+
+
+
+
+

Manage accounting periods

+
+

Create a period. All three parameters are required. A successful request returns 201 Created.

+
+
+
+
curl -X POST \
+     -H'Content-Type: application/json' \
+     -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     -d '{}' \
+     "${AVIATE}/v1/revenue/periods?periodName=2026-05&startDate=2026-05-01&endDate=2026-05-31"
+
+
+
+

List periods. Add closed=true or closed=false to filter.

+
+
+
+
curl -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     "${AVIATE}/v1/revenue/periods?closed=false" | jq .
+
+
+
+

View one period:

+
+
+
+
curl -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     "${AVIATE}/v1/revenue/periods/2026-04" | jq .
+
+
+
+
+

Close a month

+
+
    +
  1. +

    Check that the month has been processed. A recognition run must have taken place on or after the last day of the month.

    +
    2. +
  2. +

    Review the period summary. It returns the period name, the recognized amount, the deferred (not yet recognized) amount and the number of entries.

    +
    +
    +
    ```
+curl -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     "${AVIATE}/v1/revenue/periods/2026-04/summary" | jq .
+```
    +
    +
    +
    +
    +
    For figures per currency, use `currencySummary` instead:
    +
    +
    +
    +
    +
    ```
+curl -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     "${AVIATE}/v1/revenue/periods/2026-04/currencySummary" | jq .
+```
    +
    +
    +
    3. +
  3. +

    Close the period. A successful close returns 204 No Content.

    +
    +
    +
    ```
+curl -X POST \
+     -H'Content-Type: application/json' \
+     -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     -d '{}' \
+     "${AVIATE}/v1/revenue/periods/2026-04/close"
+```
    +
    +
    +
    4. +
  4. +

    If the close is rejected because unrecognized entries remain, look at the schedules involved (for example, those closed early by a cancellation). If you still want to close the month, repeat the request with force=true:

    +
    +
    +
    ```
+curl -X POST \
+     -H'Content-Type: application/json' \
+     -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     -d '{}' \
+     "${AVIATE}/v1/revenue/periods/2026-04/close?force=true"
+```
    +
    +
    +
    5. +
+
+
+
+

Reopen a month

+
+

A successful reopen returns 204 No Content. The request is rejected if the period does not exist or is not closed.

+
+
+
+
curl -X POST \
+     -H'Content-Type: application/json' \
+     -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     -d '{}' \
+     "${AVIATE}/v1/revenue/periods/2026-04/reopen"
+
+
+
+
+

Run reports

+
+

Revenue waterfall. Recognized and deferred revenue per period and currency. All parameters are optional: startPeriod and endPeriod (YYYY-MM, inclusive) and currency.

+
+
+
+
curl -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     "${AVIATE}/v1/revenue/reports/waterfall?startPeriod=2026-01&endPeriod=2026-06&currency=USD" | jq .
+
+
+
+

Revenue by plan. Total, recognized and deferred amounts and the number of schedules per plan, across the whole tenant. Takes no parameters.

+
+
+
+
curl -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     "${AVIATE}/v1/revenue/reports/by-plan" | jq .
+
+
+
+

Recognition rate. 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.

+
+
+
+
curl -H"Authorization: Bearer ${ID_TOKEN}" \
+     -H"X-killbill-apiKey: ${API_KEY}" \
+     -H"X-killbill-apisecret: ${API_SECRET}" \
+     "${AVIATE}/v1/revenue/reports/recognition-rate" | jq .
+
+
+
+
+
+
+

Examples

+
+
+

Example 1: Monthly subscription

+
+

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

+
+
+
    +
  • +

    Aviate creates a straight-line schedule with a total of 31.00, all deferred.

    +
    • +
  • +

    The service period is 31 days, so Aviate creates 31 entries of 1.00, dated 2026-01-01 to 2026-01-31, all in period 2026-01.

    +
    • +
  • +

    Each daily run recognizes the entries dated up to that day. After the run on 2026-01-10, 10.00 is recognized and 21.00 is deferred.

    +
    • +
  • +

    After the run on 2026-01-31, the full 31.00 is recognized and the schedule is closed.

    +
    • +
+
+
+
+

Example 2: Quarterly subscription spanning three months

+
+

A customer is invoiced USD 90.00 for a quarterly plan covering 2026-01-01 to 2026-04-01, which is 90 days. The daily amount is 1.00, so the revenue falls into three periods:

+
+
+

| Period | Days | Revenue | +|--------|------|---------| +| 2026-01 | 31 | 31.00 | +| 2026-02 | 28 | 28.00 | +| 2026-03 | 31 | 31.00 | +| Total | 90 | 90.00 |

+
+
+

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

+
+
+
+

Example 3: Rounding

+
+

A customer is invoiced USD 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.

    +
    • +
+
+
+
+

Example 4: One-time setup fee

+
+

A customer is invoiced a fixed USD 250.00 setup fee with a service start date of 2026-04-15.

+
+
+
    +
  • +

    Aviate creates an immediate schedule with one entry of 250.00 dated 2026-04-15, in period 2026-04.

    +
    • +
  • +

    The first recognition run on or after 2026-04-15 recognizes the full amount and closes the schedule.

    +
    • +
+
+
+
+

Example 5: Month-end close

+
+

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

+
+
+
    +
  1. +

    The daily run on 2026-04-30 or later has recognized all April entries.

    +
    2. +
  2. +

    GET /v1/revenue/periods/2026-04/summary shows the recognized total for April with a deferred amount of 0.

    +
    3. +
  3. +

    POST /v1/revenue/periods/2026-04/close returns 204 No Content.

    +
    4. +
  4. +

    GET /v1/revenue/periods?closed=true now lists 2026-04 with the closing date and user.

    +
    5. +
+
+
+

If a subscription had been cancelled in the middle of April, its remaining April days would still be unrecognized. Step 3 would be rejected with Cannot close period 2026-04: N unrecognized entries remain. After review, the team would close the month with force=true.

+
+
+
+

Example 6: Mid-period cancellation

+
+

A USD 31.00 schedule covers 2026-01-01 to 2026-02-01. By 2026-01-15, 15.00 has been recognized. The subscription is then cancelled with effect from 2026-01-16, and Kill Bill credits the unused 16.00.

+
+
+
    +
  • +

    Aviate records a reversal entry of −16.00, ends the schedule on 2026-01-16 and closes it.

    +
    • +
  • +

    Days after 2026-01-16 are not recognized.

    +
    • +
  • +

    The unrecognized January days stay in period 2026-01. Closing January therefore requires force=true.

    +
    • +
  • +

    The reversal entry has no accounting period, so it does not appear in the January period summary.

    +
    • +
+
+
+
+
+
+ + + + \ No newline at end of file diff --git a/userguide/preview/aviate-revenue-recognition.adoc b/userguide/preview/aviate-revenue-recognition.adoc index 10ef8daf9..b196f48b3 100644 --- a/userguide/preview/aviate-revenue-recognition.adoc +++ b/userguide/preview/aviate-revenue-recognition.adoc @@ -2,17 +2,21 @@ include::{sourcedir}/includes/insider-preview-card.adoc[] +[NOTE] +*Beta.* Revenue Recognition is an Insider Preview (beta) feature. Its behavior, API and screens can change between releases. The amounts, identifiers and screens on this page are examples, some of them produced with sample data. Always check revenue figures against your own invoices before you use them to close a month, and send your feedback through Kill Bill support. + == Introduction The Aviate Revenue Recognition module manages when revenue is recognized from the invoices that Kill Bill generates. It spreads each invoiced amount over the period in which the service is delivered, and tracks how much of it has been recognized and how much is still deferred. Finance teams get visibility into recognized vs. deferred revenue through monthly accounting periods that they can close and reopen. -The module applies concepts from ASC 606 (Revenue from Contracts with Customers): revenue is recognized as the service is delivered. Aviate calculates and reports revenue from billing data. It does not post entries to a general ledger or export journals. Your finance team remains responsible for confirming that the resulting treatment meets the accounting standards that apply to you. +Your accounting policy remains the responsibility of your finance team. Using this module does not by itself make your accounting compliant with a revenue standard such as ASC 606 or IFRS 15. Key capabilities include: * *Automatic revenue schedules* -- every eligible invoice item gets a schedule that spreads its amount over the item's service period * *Daily recognition* -- a background process recognizes revenue as each day of service is delivered * *Accounting periods* -- monthly periods that are created automatically and can be closed, reopened and reported on +* *Contract-aware allocation* -- revenue allocated across the subscriptions of a contract using relative standalone selling prices * *Reports* -- period summaries, a period-by-period waterfall of recognized and deferred revenue, revenue by plan and recognition rate * *Schedule lookups* -- schedules and their daily entries by invoice item, account, subscription, plan, currency or contract @@ -27,7 +31,7 @@ Each schedule is split into dated *revenue entries*. An entry is recognized once [[revrec-recognition-methods]] === Recognition Methods -The recognition method depends only on the type of the invoice item. It cannot be configured per plan, product or customer. +The recognition method depends only on the type of the invoice item. In this release it cannot be set per plan, product or customer. [cols="1,1,2", options="header"] |=== @@ -41,7 +45,7 @@ The recognition method depends only on the type of the invoice item. It cannot b | Straight-line | Evenly, one entry per day of the item's service period -| Fixed (one-time) +| Fixed (for example a setup fee) | Immediate | One entry for the full amount on the service start date @@ -54,14 +58,37 @@ Items with a zero or negative amount, and other item types such as taxes and cre For straight-line schedules: -* The service period runs from the item's start date up to, but *not including*, its end date. A 1 January to 1 February period is 31 days. -* The daily amount is the total divided by the number of days, rounded to nine decimal places. +* The service period runs from the item's start date up to, but *not including*, its end date. A 1 January to 1 February period covers the 31 days of January. +* The daily amount is the total divided by the number of days, rounded to nine decimal places. Monthly amounts therefore follow the number of days in each month. * The last day takes any rounding difference, so the entries always add up exactly to the schedule total. +* When a contract allocation applies (see <>), the schedule total is the allocated amount instead of the invoice item amount. -For example: +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: + +[cols="2,1,1", options="header"] +|=== +| Month | Days | Recognized -* A $1,200 annual subscription billed for 1 January 2026 to 1 January 2027 is spread over 365 days, at about $3.29 a day. January (31 days) receives $101.92, February (28 days) $92.05 and April (30 days) $98.63. -* A $500 one-time setup fee is recognized in full on its service start date. +| January 2026 +| 31 +| $101.92 + +| February 2026 +| 28 +| $92.05 + +| April 2026 +| 30 +| $98.63 + +| Full year +| 365 +| $1,200.00 +|=== + +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. === Accounting Periods @@ -75,7 +102,18 @@ 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. [NOTE] -*Note:* Closing a period does not block billing. Kill Bill still accepts invoices, credits, adjustments and payments dated in a closed period, and adjustments still update the affected revenue schedules. See <>. +*Note:* Closing a period does not block billing. Kill Bill still accepts invoices, credits, adjustments and payments dated in a closed period. See <>. + +=== Contract Revenue Allocation + +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): + +. Each subscription in the contract (a _contract term_) is treated as a performance obligation. +. The SSP for each term is looked up from the SSPs you configure for its plan, phase and currency. +. The transaction price is allocated across the terms in proportion to their SSPs. +. Each allocated amount is recognized using the recognition method of its invoice items. + +See <> for details. == Getting Started with Revenue Recognition @@ -117,12 +155,60 @@ Full API documentation is available at https://apidocs.killbill.io/aviate-revrec 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 (`{}`). +== Using Revenue Recognition in Aviate + +Insider Preview participants get access to the Revenue Recognition screens in Aviate. The screenshots below were taken with sample data: plans, amounts, accounts and email addresses are examples. The layout can change during the preview. + +[cols="1,3", options="header"] +|=== +| Screen | What it shows + +| Dashboard +| Recognized and deferred revenue, recent accounting periods, and the plans with the most revenue + +| Waterfall +| Recognized and deferred revenue per accounting period, filtered by period range and currency + +| Periods +| Accounting periods, with their status and the close and reopen actions + +| Schedules +| One row per revenue schedule, filtered by method, period, account, plan or dates. Open a schedule to see its invoice, invoice item, item type, method, service period and entries + +| By Plan +| Total, recognized and deferred revenue per plan + +| Rates +| The share of revenue already recognized, per method (straight line or immediate) + +| SSP +| Standalone selling prices per plan, phase and currency, with their source and validity dates + +| Allocations +| Contract allocations: number of terms, transaction price and allocation method +|=== + +=== Accounting Periods Screen + +image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/aviate/revenue-recognition/accounting-periods.png[Accounting periods screen, example with sample data,align=center] + +* A period is either *Open* or *Closed*. +* An open period whose end date has passed is flagged *Overdue*. This is a reminder to close it, not a separate status. +* The *Close* action is offered on the oldest open period whose end date has passed, so months are closed in order. +* The *Reopen* action is offered on closed periods. +* *Closed By* shows who closed the period. + +=== Recognition Rates Screen + +image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/aviate/revenue-recognition/recognition-rates.png[Recognition rates screen, example with sample data,align=center] + +This screen compares straight-line and immediate revenue: number of schedules, total, recognized and deferred amounts, and the average number of days since invoicing. == How Revenue Is Recognized === Schedule Creation -When Kill Bill generates an invoice, Aviate creates a revenue schedule for each eligible invoice item and generates its entries (see <>). It also creates the monthly accounting periods those entries fall into, if they do not exist yet. +When Kill Bill generates an invoice, Aviate creates a revenue schedule for each eligible invoice item and generates its entries (see <>). 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. === Daily Recognition @@ -132,6 +218,8 @@ A background process runs at the configured interval, once a day by default. Eac * Updates each affected schedule's recognized and deferred amounts. * Closes a schedule once its full amount has been recognized. +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. + === Recognizing Revenue for a Specific Month In production, revenue for a month is recognized by the regular runs as its days pass. All of a month's entries have been processed once a run has taken place on or after the last day of that month. @@ -139,7 +227,7 @@ In production, revenue for a month is recognized by the regular runs as its days The month-end workflow is: . Wait for a recognition run on or after the last day of the month. -. Review the month with the period summary. +. Review the month with the period summary and the waterfall report. . Close the period. See <> for the steps. @@ -259,7 +347,7 @@ If you bill in more than one currency, use the currency summary. The plain summa To close a month: . Check that a recognition run has taken place on or after the last day of the month. -. Review the period summary. +. Review the period summary and the waterfall report for that month. . Close the period. A successful close returns `204 No Content`. [source,bash] @@ -274,7 +362,7 @@ curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/revenue/periods/2026-01/close" 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`. -After reviewing the remaining entries, you can override this check with `force=true`: +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 <>). You can then override this check with `force=true`: [source,bash] ---- @@ -286,7 +374,7 @@ curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/revenue/periods/2026-01/close?f -d '{}' ---- -A month that contains a mid-period cancellation or adjustment can only be closed with `force=true` (see <>). +Closing a period does not block new invoices, credits or adjustments for that month. See <>. === Reopening a Period @@ -334,7 +422,7 @@ All parameters are optional: | Only include revenue in this currency, for example `USD` |=== -Each row contains the accounting period, the currency, the recognized amount, the deferred (not yet recognized) amount and the number of entries. +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. === Revenue by Plan @@ -362,7 +450,7 @@ curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/reports/recognition-rate" \ === How Reports Are Calculated -Reports are built from two different sources. Their figures can differ after cancellations, adjustments or credits. +Reports are built from two different sources. Their figures can differ after adjustments, credits or cancellations. [cols="1,2,2", options="header"] |=== @@ -389,7 +477,121 @@ Reports are built from two different sources. Their figures can differ after can | All currencies added together |=== -In entry-based reports, "deferred" is the total of entries *not yet recognized*. This includes entries left unrecognized after a cancellation or adjustment. +In entry-based reports, "deferred" is the total of entries *not yet recognized*. + +[[revrec-allocation-details]] +== Contract Revenue Allocation + +When a contract covers several subscriptions, Aviate uses standalone selling prices (SSP) to allocate the contract's transaction price across them. + +=== How Allocation Works + +Each subscription in the contract is a contract term. Consider a contract with three subscriptions whose first invoice totals $15,000: + +* Enterprise subscription: $10,000/year (SSP: $10,000) +* Implementation services: $3,000 one-time (SSP: $5,000) +* Premium support: $2,000/year (SSP: $2,000) +* *Transaction price*: $15,000 + +Using relative SSP allocation: + +[cols="1,1,1,1", options="header"] +|=== +| Contract term | SSP | SSP % | Allocated Revenue + +| Subscription +| $10,000 +| 58.8% +| $8,823.53 + +| Implementation +| $5,000 +| 29.4% +| $4,411.76 + +| Support +| $2,000 +| 11.8% +| $1,764.71 +|=== + +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: + +* *When allocation happens.* A contract is allocated automatically when its first invoice is generated. The transaction price is the total of that invoice's positive charges for the contract's subscriptions. Once a contract has allocations, later invoices do not recalculate them, so later changes to SSPs do not affect it. +* *Which SSP is used.* For each term, Aviate uses the most recent SSP for the term's plan, phase and currency that is in effect on the allocation date. +* *Missing SSPs.* If a term has no SSP in effect, its SSP is taken as an equal share of the transaction price (the transaction price divided by the number of terms). +* *How allocations are used.* Once a contract term has an allocation, Aviate uses the allocated amount as the total of every revenue schedule created for that subscription's invoice items, instead of the invoice item amount. +* *Allocating explicitly.* You can run the allocation yourself with a transaction price of your choice (see below). Doing so replaces any existing allocation for the contract's terms. Schedules that already exist are not recalculated. +* *Subscriptions without a contract.* Subscriptions that are not part of a contract, such as self-service sign-ups, get revenue schedules and daily recognition, but no allocation. + +We recommend setting explicit SSPs for every plan and phase used in contracts, so that allocations are consistent and auditable. + +=== Setting Standalone Selling Prices + +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: + +[source,bash] +---- +curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/revenue/ssp?planName=implementation-services&phaseName=implementation-services-fixedterm¤cy=USD&amount=5000.00&effectiveDate=2026-01-01" \ + -H "Authorization: Bearer ${ID_TOKEN}" \ + -H "X-Killbill-ApiKey: ${API_KEY}" \ + -H "X-Killbill-ApiSecret: ${API_SECRET}" \ + -H "Content-Type: application/json" \ + -d '{}' +---- + +[cols="1,1,3", options="header"] +|=== +| Parameter | Required | Description + +| `planName` +| Yes +| Kill Bill plan name + +| `phaseName` +| Yes +| Kill Bill phase name of the plan + +| `currency` +| Yes +| Currency of the SSP, for example `USD` + +| `amount` +| Yes +| Standalone selling price + +| `effectiveDate` +| Yes +| First day the SSP applies (`YYYY-MM-DD`) + +| `expirationDate` +| No +| Last day the SSP applies. Leave empty for no end date. + +| `source` +| No +| Free-text label for where the price comes from. Defaults to `LIST_PRICE`. +|=== + +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. + +=== Allocating a Contract Explicitly + +`currency` and `transactionPrice` are required. The response lists the resulting allocation for each contract term. + +[source,bash] +---- +curl -X POST "${KB_URL}/plugins/aviate-plugin/v1/revenue/contracts/${CONTRACT_ID}/allocations?currency=USD&transactionPrice=15000.00" \ + -H "Authorization: Bearer ${ID_TOKEN}" \ + -H "X-Killbill-ApiKey: ${API_KEY}" \ + -H "X-Killbill-ApiSecret: ${API_SECRET}" \ + -H "Content-Type: application/json" \ + -d '{}' +---- + +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. == Viewing Revenue Details @@ -435,10 +637,15 @@ curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/schedules?accountId=${ACCOUNT_I === By Contract -List the revenue schedules of a contract's subscriptions: +Contract allocations and the revenue schedules of a contract are available through two calls. The contract ID is a UUID. [source,bash] ---- +curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/contracts/${CONTRACT_ID}/allocations" \ + -H "Authorization: Bearer ${ID_TOKEN}" \ + -H "X-Killbill-ApiKey: ${API_KEY}" \ + -H "X-Killbill-ApiSecret: ${API_SECRET}" + curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/contracts/${CONTRACT_ID}/schedules" \ -H "Authorization: Bearer ${ID_TOKEN}" \ -H "X-Killbill-ApiKey: ${API_KEY}" \ @@ -477,7 +684,6 @@ curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/${SCHEDULE_ID}/entriesPerSchedu -H "X-Killbill-ApiSecret: ${API_SECRET}" ---- -[[revrec-business-rules]] == Business Rules and Constraints === Recognition @@ -489,26 +695,24 @@ curl "${KB_URL}/plugins/aviate-plugin/v1/revenue/${SCHEDULE_ID}/entriesPerSchedu * Closing a period does not block billing. Kill Bill still accepts invoices, credits, adjustments and payments dated in a closed period. * If a new invoice item has service dates in a closed period, Aviate does not create its revenue entries. If you expect back-dated invoices, reopen the affected period *before* the invoice is generated. -* Adjustments and credits processed after a period is closed still update the affected schedules. -[[revrec-cancellations]] -=== Cancellations and Adjustments - -When an invoice item is reduced after its schedule exists, for example by an item adjustment or by the credit Kill Bill issues when a subscription is cancelled or changed mid-period: +=== Data You Cannot Edit -* If the item still has deferred revenue, Aviate records a *reversal entry* for the adjustment amount, ends the schedule at the adjustment date and closes it. Days after that date are not recognized. -* If the item's revenue has already been fully recognized, the schedule is not changed and no reversal is recorded. -* The days that were not recognized remain in their month as unrecognized entries. Closing a month that contains a mid-period cancellation or adjustment therefore requires `force=true`. -* Reversal entries are not assigned to an accounting period, so they do not appear in period summaries or in a waterfall that has a start period. +Revenue schedules and entries are derived from invoices. You cannot create, edit or delete them directly. -=== Account Credits +[[revrec-adjustments]] +== Invoice Adjustments, Credits and Cancellations -* A credit created on its own, outside an invoice that also contains charges, reduces the deferred revenue of the account's open schedules. You cannot choose which schedules a credit is applied to. -* Credits that appear on the same invoice as recurring, usage, fixed or external charges are not treated as revenue adjustments and do not change any schedule. +Adjustments, credits and cancellations can change revenue schedules. How these changes affect recognized and deferred revenue, and how they interact with closed periods, is still being finalized in this preview. During the preview, review revenue for any month that contains an adjustment, a credit or a mid-period cancellation before you close it. If you are testing this module, tell us which treatment your accounting policy requires. -=== Data You Cannot Edit +== Not Included in This Preview -Revenue schedules and entries are derived from invoices. You cannot create, edit or delete them directly. To change revenue, change the underlying invoice, for example with an item adjustment. +* Accounting journal entries, or an export to an ERP or general ledger +* A recognition method set per plan or per product +* Equal monthly amounts with prorated first and last months. Straight-line revenue is calculated per day +* Editing or reversing a revenue entry by hand. Schedules are created from invoices +* Approval of a schedule before recognition +* Blocking invoices, credits or adjustments in a closed period == Examples @@ -565,13 +769,4 @@ On `2026-05-02`, the finance team closes April: . `POST /v1/revenue/periods/2026-04/close` returns `204 No Content`. . `GET /v1/revenue/periods?closed=true` now lists `2026-04` with the closing date and user. -If a subscription had been cancelled in the middle of April, its remaining April days would still be unrecognized. Step 3 would then be rejected with `Cannot close period 2026-04: N unrecognized entries remain`, and after review the team would close the month with `force=true`. - -=== Mid-Period Cancellation - -A $31.00 schedule covers `2026-01-01` to `2026-02-01`. By `2026-01-15`, $15.00 has been recognized. The subscription is then cancelled with effect from `2026-01-16`, and Kill Bill credits the unused $16.00. - -* Aviate records a reversal entry of −$16.00, ends the schedule on `2026-01-16` and closes it. -* Days after `2026-01-16` are not recognized. -* The unrecognized January days stay in period `2026-01`, so closing January requires `force=true`. -* The reversal entry has no accounting period, so it does not appear in the January period summary. +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`. \ No newline at end of file diff --git a/userguide/tutorials/email-notification-plugin.html b/userguide/tutorials/email-notification-plugin.html new file mode 100644 index 000000000..281fd4ba6 --- /dev/null +++ b/userguide/tutorials/email-notification-plugin.html @@ -0,0 +1,1594 @@ + + + + + + + +Email Notification Plugin + + + + + + + + + + + \ No newline at end of file From 9aede74177bc9acc165c0c61c6e61cf506b88389 Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:27:55 +0530 Subject: [PATCH 3/5] Delete unnecessary files --- .../aviate-revenue-recognition-v2.adoc | 454 ----- .../aviate-revenue-recognition-v2.html | 1501 ---------------- .../tutorials/email-notification-plugin.html | 1594 ----------------- 3 files changed, 3549 deletions(-) delete mode 100644 userguide/preview/aviate-revenue-recognition-v2.adoc delete mode 100644 userguide/preview/aviate-revenue-recognition-v2.html delete mode 100644 userguide/tutorials/email-notification-plugin.html diff --git a/userguide/preview/aviate-revenue-recognition-v2.adoc b/userguide/preview/aviate-revenue-recognition-v2.adoc deleted file mode 100644 index dc3743bbb..000000000 --- a/userguide/preview/aviate-revenue-recognition-v2.adoc +++ /dev/null @@ -1,454 +0,0 @@ -# Revenue Recognition - -The Aviate Revenue Recognition module turns the invoices that Kill Bill produces into revenue schedules. It spreads each invoiced amount over the period in which the service is delivered and tracks, day by day, how much of that amount has been recognized as revenue and how much is still deferred. Finance teams use it to see deferred and recognized revenue per accounting month, and to close and reopen those months. - -This guide describes the functionality that is available today, the rules it follows, and how to use it through the Aviate API. - -## Table of Contents - -- [Overview](#overview) -- [Key Features](#key-features) -- [Accounting Periods](#accounting-periods) -- [Revenue Recognition Process](#revenue-recognition-process) -- [Business Rules and Constraints](#business-rules-and-constraints) -- [Usage Instructions](#usage-instructions) -- [Examples](#examples) - -## Overview - -When you bill a customer in advance, for example a monthly or annual subscription, the cash and the invoice arrive before the service is delivered. Accounting practice generally treats that amount as deferred revenue that becomes recognized revenue over the service period. - -The Revenue Recognition module automates this for invoices generated by Kill Bill: - -- It creates a **revenue schedule** for each eligible invoice item as soon as the invoice is generated. -- It splits the schedule into dated **revenue entries**, either one per day of the service period or a single entry for one-time charges. -- A background process marks entries as **recognized** once their date is reached. -- Every entry belongs to an **accounting period** (a calendar month), which you can close at month-end and reopen if needed. -- Reports show recognized and deferred revenue by period, by currency, by plan and by recognition method. - -The module answers questions such as: - -- How much of what we invoiced has been earned so far, and how much is still deferred? -- How much revenue was recognized in March? -- Which schedules does a given account or subscription have, and where does each one stand? - -> **Note:** The module calculates and reports revenue from billing data. It does not post entries to a general ledger and does not export journals. Whether its output meets a particular accounting standard is for your finance team to determine. - -## Key Features - -| Feature | Description | -|---------|-------------| -| Automatic revenue schedules | A schedule is created for every eligible invoice item when the invoice is generated. No manual setup is required. | -| Two recognition methods | **Straight-line** (daily) for recurring and usage charges; **immediate** for fixed (one-time) and external charges. | -| Daily recognition | A background process recognizes all entries whose date has been reached. By default it runs once a day. | -| Monthly accounting periods | Periods named `YYYY-MM` are created automatically as revenue entries are generated. You can also create periods yourself. | -| Period close and reopen | Close a month once all of its revenue has been recognized; reopen it if you need to. | -| Adjustment handling | Invoice item adjustments, cancellation credits and standalone account credits are reflected in the affected schedules. | -| Schedule lookup | Look up schedules by invoice item or schedule ID, or list them with filters such as account, subscription, plan, currency and status. | -| Revenue reports | Period summary, per-currency period summary, revenue waterfall, revenue by plan and recognition rate. | - -### Before you begin - -Revenue recognition is **disabled by default**. Your Aviate administrator enables it in the plugin configuration: - -| Property | Default | Description | -|----------|---------|-------------| -| `com.killbill.billing.plugin.aviate.enableRevenueRecognition` | `false` | Set to `true` to create revenue schedules for new invoices and to start the daily recognition process. | -| `com.killbill.billing.plugin.aviate.revenueRecognition.delaySeconds` | `86400` (one day) | How often the recognition process runs, in seconds. | - -Revenue schedules are created as invoices are generated. Enable the feature before you start billing the customers whose revenue you want to track. - -## Accounting Periods - -An accounting period groups revenue entries by calendar month. Periods are identified by name, in the format `YYYY-MM` (for example `2026-04`). - -### How periods are created - -- **Automatically.** When Aviate creates revenue entries for an invoice item, it creates any monthly period that does not already exist, from the first to the last day of that month. -- **Manually.** You can create a period ahead of time by giving it a name, a start date and an end date. - -Every revenue entry is assigned to the period named after the month of its date. For example, an entry dated `2026-04-17` belongs to period `2026-04`. When you create a period manually, use the same `YYYY-MM` name with the first and last day of the month. A period with any other name receives no revenue entries. - -### Supported operations - -| Operation | What it does | -|-----------|--------------| -| Create | Creates a period with a name, start date and end date. The name must be unique, and the end date cannot be before the start date. | -| List | Lists all periods. Can be filtered to only open or only closed periods. | -| View | Shows one period: its dates, whether it is closed, and when and by whom it was closed. | -| Close | Closes an open period. Rejected if the period still contains unrecognized revenue entries, unless you force the close. | -| Reopen | Reopens a closed period. Its unrecognized entries become eligible for recognition again. | -| Summary | Shows recognized and deferred revenue and the number of entries in the period, for all currencies combined or per currency. | - -### Closing a period - -To close a period: - -- The period must exist and must not already be closed. -- All revenue entries dated in that period must already be recognized. Otherwise the close is rejected with a message like `Cannot close period 2026-04: 12 unrecognized entries remain`. -- You can override this check with the `force` option. Use it when you have reviewed the remaining entries and still want to close the month. For a common case where this is needed, see [Cancellations and adjustments](#cancellations-and-adjustments). - -When a period is closed: - -- The date and the user who closed it are recorded. -- The daily recognition process no longer recognizes any remaining unrecognized entries in that period. -- Aviate does not create revenue entries for new invoice items whose service dates fall in that period (see [Closed periods](#closed-periods)). - -### Reopening a period - -Only a closed period can be reopened. 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. - -## Revenue Recognition Process - -### 1. Schedule creation (when an invoice is generated) - -When Kill Bill generates an invoice, Aviate examines each invoice item and creates one revenue schedule per eligible item: - -| Invoice item type | Recognition method | How the amount is spread | -|-------------------|--------------------|--------------------------| -| Recurring | Straight-line | Evenly, one entry per day of the service period | -| Usage | Straight-line | Evenly, one entry per day of the service period | -| Fixed (one-time) | Immediate | One entry for the full amount on the service start date | -| External charge | Immediate | One entry for the full amount on the service start date | - -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. - -Each schedule records: - -- The invoice, invoice item, account, subscription, plan and phase it came from. -- Its currency and total amount. -- Its service period and recognition method. -- Its running **recognized** and **deferred** amounts. At creation, the full amount is deferred. -- Whether it is closed, meaning fully recognized or ended early by an adjustment. - -### 2. Straight-line calculation - -For straight-line schedules: - -- The service period runs from the item's start date up to, but **not including**, its end date. A 1 January to 1 February period is 31 days. -- The daily amount is the total divided by the number of days, rounded to nine decimal places. -- The last day takes any rounding difference, so the entries always add up exactly to the schedule total. - -### 3. Daily recognition - -A background process runs at the configured interval, once a day by default. Each run: - -- Recognizes every unrecognized entry dated **on or before the current date (UTC)** in an open period, including entries dated today. -- Updates each affected schedule's recognized and deferred amounts. -- Closes a schedule once its full amount has been recognized. - -### Recognizing revenue for a specific month - -There is no customer-facing operation that runs recognition on demand for a chosen date or month. Revenue for a month is recognized by the regular runs as its days pass. All of a month's entries have been processed once a run has taken place on or after the last day of that month. - -The month-end workflow is: - -1. Wait for a recognition run on or after the last day of the month. -2. Review the month with the period summary. -3. Close the period. - -See [Close a month](#close-a-month) for the steps. - -## Business Rules and Constraints - -### Recognition rules - -- The recognition method depends only on the invoice item type. It cannot be configured per plan, product or customer. -- Recognition follows the service dates on the invoice item, not the invoice date or the payment date. Revenue is recognized whether or not the invoice has been paid. -- Revenue is always assigned to calendar months. Custom fiscal calendars (for example 4-4-5 periods) are not supported. - -### Closed periods - -- Closing a period **does not block billing**. Invoices, credits, adjustments and payments dated in a closed period are still accepted by Kill Bill. -- If a new invoice item has service dates in a closed period, Aviate does not create its revenue entries. If you expect back-dated invoices, reopen the affected period **before** the invoice is generated. -- Adjustments and credits processed after a period is closed still update the affected schedules (see below). - -### Cancellations and adjustments - -When an invoice item is reduced after its schedule exists, for example by an item adjustment or by the credit Kill Bill issues when a subscription is cancelled or changed mid-period: - -- If the item still has deferred revenue, Aviate records a **reversal entry** for the adjustment amount, ends the schedule at the adjustment date and closes it. Days after that date are not recognized. -- If the item's revenue has already been fully recognized, the schedule is not changed and no reversal is recorded. -- The days that were not recognized remain in their month as unrecognized entries. **Closing a month that contains a mid-period cancellation or adjustment therefore requires the `force` option.** -- Reversal entries are not assigned to an accounting period, so they do not appear in period summaries or in a waterfall that has a start period. - -### Account credits - -- A credit created on its own, outside an invoice that also contains charges, reduces the deferred revenue of the account's open schedules. You cannot choose which schedules a credit is applied to. -- Credits that appear on the same invoice as recurring, usage, fixed or external charges are not treated as revenue adjustments and do not change any schedule. - -### Reports - -Reports are built from two different sources. Their figures can differ after cancellations, adjustments or credits. - -| Report | Built from | Currency handling | -|--------|-----------|-------------------| -| Period summary | Revenue entries in the period | All currencies added together | -| Period currency summary | Revenue entries in the period | One row per currency | -| Revenue waterfall | Revenue entries, by period | One row per period and currency | -| Revenue by plan | Schedule totals | All currencies added together | -| Recognition rate | Schedule totals, by recognition method | All currencies added together | - -- In entry-based reports, "deferred" is the total of entries **not yet recognized**. This includes entries left unrecognized after a cancellation or adjustment. -- For tenants that bill in more than one currency, use the period currency summary or the waterfall to avoid adding amounts in different currencies together. - -### Access and permissions - -- All revenue operations apply to the tenant identified by the Kill Bill API key and secret on the request. -- When role-based access control is enabled in Aviate, any authenticated role can read revenue data. Creating, closing and reopening periods requires one of the roles `finance_admin`, `finance_vp`, `system_admin`, `admin` or `super_admin`. - -### Data you cannot edit - -Revenue schedules and entries are derived from invoices. You cannot create, edit or delete them directly. To change revenue, change the underlying invoice, for example with an item adjustment. - -## Usage Instructions - -All operations are available through the Aviate REST API under: - -``` -http://:8080/plugins/aviate-plugin/v1/revenue -``` - -Every request needs: - -- `Authorization: Bearer ${ID_TOKEN}` (your Aviate token) -- `X-killbill-apiKey` and `X-killbill-apisecret` (your tenant credentials) - -Parameters are passed in the query string. As with other Aviate actions, send `POST` requests with `Content-Type: application/json` and an empty JSON body (`{}`). - -The examples below use these shell variables: - -``` -export AVIATE=http://127.0.0.1:8080/plugins/aviate-plugin -export API_KEY= -export API_SECRET= -``` - -### Look up revenue schedules - -**List schedules** with any combination of filters: - -| Query parameter | Description | -|-----------------|-------------| -| `accountId` | Schedules of one account | -| `subscriptionId` | Schedules of one subscription | -| `planName` | Schedules for one plan | -| `currency` | Schedules in one currency, for example `USD` | -| `closed` | `true` for closed schedules, `false` for open ones | -| `servicePeriodStart` | Schedules whose service period starts on or after this date (`YYYY-MM-DD`) | -| `offset`, `limit` | Paging. `limit` defaults to and cannot exceed 1000. | - -Results are returned newest first. - -``` -curl -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - "${AVIATE}/v1/revenue/schedules?accountId=${ACCOUNT_ID}&closed=false&limit=50" | jq . -``` - -**Get the schedule of an invoice item**, using the Kill Bill invoice item ID: - -``` -curl -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - "${AVIATE}/v1/revenue/${INVOICE_ITEM_ID}/schedule" | jq . -``` - -**Get a schedule by its ID.** Schedule IDs are numbers and are returned in the schedule details. - -``` -curl -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - "${AVIATE}/v1/revenue/schedules/${SCHEDULE_ID}" | jq . -``` - -**List the revenue entries of a schedule**, showing each entry's date, amount, period and whether it has been recognized: - -``` -curl -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - "${AVIATE}/v1/revenue/${SCHEDULE_ID}/entriesPerSchedule" | jq . -``` - -### Manage accounting periods - -**Create a period.** All three parameters are required. A successful request returns `201 Created`. - -``` -curl -X POST \ - -H'Content-Type: application/json' \ - -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - -d '{}' \ - "${AVIATE}/v1/revenue/periods?periodName=2026-05&startDate=2026-05-01&endDate=2026-05-31" -``` - -**List periods.** Add `closed=true` or `closed=false` to filter. - -``` -curl -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - "${AVIATE}/v1/revenue/periods?closed=false" | jq . -``` - -**View one period:** - -``` -curl -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - "${AVIATE}/v1/revenue/periods/2026-04" | jq . -``` - -### Close a month - -1. **Check that the month has been processed.** A recognition run must have taken place on or after the last day of the month. - -2. **Review the period summary.** It returns the period name, the recognized amount, the deferred (not yet recognized) amount and the number of entries. - - ``` - curl -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - "${AVIATE}/v1/revenue/periods/2026-04/summary" | jq . - ``` - - For figures per currency, use `currencySummary` instead: - - ``` - curl -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - "${AVIATE}/v1/revenue/periods/2026-04/currencySummary" | jq . - ``` - -3. **Close the period.** A successful close returns `204 No Content`. - - ``` - curl -X POST \ - -H'Content-Type: application/json' \ - -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - -d '{}' \ - "${AVIATE}/v1/revenue/periods/2026-04/close" - ``` - -4. **If the close is rejected because unrecognized entries remain,** look at the schedules involved (for example, those closed early by a cancellation). If you still want to close the month, repeat the request with `force=true`: - - ``` - curl -X POST \ - -H'Content-Type: application/json' \ - -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - -d '{}' \ - "${AVIATE}/v1/revenue/periods/2026-04/close?force=true" - ``` - -### Reopen a month - -A successful reopen returns `204 No Content`. The request is rejected if the period does not exist or is not closed. - -``` -curl -X POST \ - -H'Content-Type: application/json' \ - -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - -d '{}' \ - "${AVIATE}/v1/revenue/periods/2026-04/reopen" -``` - -### Run reports - -**Revenue waterfall.** Recognized and deferred revenue per period and currency. All parameters are optional: `startPeriod` and `endPeriod` (`YYYY-MM`, inclusive) and `currency`. - -``` -curl -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - "${AVIATE}/v1/revenue/reports/waterfall?startPeriod=2026-01&endPeriod=2026-06¤cy=USD" | jq . -``` - -**Revenue by plan.** Total, recognized and deferred amounts and the number of schedules per plan, across the whole tenant. Takes no parameters. - -``` -curl -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - "${AVIATE}/v1/revenue/reports/by-plan" | jq . -``` - -**Recognition rate.** 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. - -``` -curl -H"Authorization: Bearer ${ID_TOKEN}" \ - -H"X-killbill-apiKey: ${API_KEY}" \ - -H"X-killbill-apisecret: ${API_SECRET}" \ - "${AVIATE}/v1/revenue/reports/recognition-rate" | jq . -``` - -## Examples - -### Example 1: Monthly subscription - -A customer is invoiced **USD 31.00** for a monthly plan covering `2026-01-01` to `2026-02-01`. - -- Aviate creates a straight-line schedule with a total of 31.00, all deferred. -- The service period is 31 days, so Aviate creates 31 entries of 1.00, dated `2026-01-01` to `2026-01-31`, all in period `2026-01`. -- Each daily run recognizes the entries dated up to that day. After the run on `2026-01-10`, 10.00 is recognized and 21.00 is deferred. -- After the run on `2026-01-31`, the full 31.00 is recognized and the schedule is closed. - -### Example 2: Quarterly subscription spanning three months - -A customer is invoiced **USD 90.00** for a quarterly plan covering `2026-01-01` to `2026-04-01`, which is 90 days. The daily amount is 1.00, so the revenue falls into three periods: - -| Period | Days | Revenue | -|--------|------|---------| -| `2026-01` | 31 | 31.00 | -| `2026-02` | 28 | 28.00 | -| `2026-03` | 31 | 31.00 | -| **Total** | **90** | **90.00** | - -At the end of January, 31.00 is recognized and 59.00 is still deferred. - -### Example 3: Rounding - -A customer is invoiced **USD 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. - -### Example 4: One-time setup fee - -A customer is invoiced a fixed **USD 250.00** setup fee with a service start date of `2026-04-15`. - -- Aviate creates an immediate schedule with one entry of 250.00 dated `2026-04-15`, in period `2026-04`. -- The first recognition run on or after `2026-04-15` recognizes the full amount and closes the schedule. - -### Example 5: Month-end close - -On `2026-05-02`, the finance team closes April: - -1. The daily run on `2026-04-30` or later has recognized all April entries. -2. `GET /v1/revenue/periods/2026-04/summary` shows the recognized total for April with a deferred amount of 0. -3. `POST /v1/revenue/periods/2026-04/close` returns `204 No Content`. -4. `GET /v1/revenue/periods?closed=true` now lists `2026-04` with the closing date and user. - -If a subscription had been cancelled in the middle of April, its remaining April days would still be unrecognized. Step 3 would be rejected with `Cannot close period 2026-04: N unrecognized entries remain`. After review, the team would close the month with `force=true`. - -### Example 6: Mid-period cancellation - -A USD 31.00 schedule covers `2026-01-01` to `2026-02-01`. By `2026-01-15`, 15.00 has been recognized. The subscription is then cancelled with effect from `2026-01-16`, and Kill Bill credits the unused 16.00. - -- Aviate records a reversal entry of −16.00, ends the schedule on `2026-01-16` and closes it. -- Days after `2026-01-16` are not recognized. -- The unrecognized January days stay in period `2026-01`. Closing January therefore requires `force=true`. -- The reversal entry has no accounting period, so it does not appear in the January period summary. diff --git a/userguide/preview/aviate-revenue-recognition-v2.html b/userguide/preview/aviate-revenue-recognition-v2.html deleted file mode 100644 index 79588891d..000000000 --- a/userguide/preview/aviate-revenue-recognition-v2.html +++ /dev/null @@ -1,1501 +0,0 @@ - - - - - - - -Revenue Recognition - - - - - - -
-
-
-
-

The Aviate Revenue Recognition module turns the invoices that Kill Bill produces into revenue schedules. It spreads each invoiced amount over the period in which the service is delivered and tracks, day by day, how much of that amount has been recognized as revenue and how much is still deferred. Finance teams use it to see deferred and recognized revenue per accounting month, and to close and reopen those months.

-
-
-

This guide describes the functionality that is available today, the rules it follows, and how to use it through the Aviate API.

-
-
-
-
-

Table of Contents

-
-
-
    -
  • -

    [Overview](#overview)

    -
    • -
  • -

    [Key Features](#key-features)

    -
    • -
  • -

    [Accounting Periods](#accounting-periods)

    -
    • -
  • -

    [Revenue Recognition Process](#revenue-recognition-process)

    -
    • -
  • -

    [Business Rules and Constraints](#business-rules-and-constraints)

    -
    • -
  • -

    [Usage Instructions](#usage-instructions)

    -
    • -
  • -

    [Examples](#examples)

    -
    • -
-
-
-
-
-

Overview

-
-
-

When you bill a customer in advance, for example a monthly or annual subscription, the cash and the invoice arrive before the service is delivered. Accounting practice generally treats that amount as deferred revenue that becomes recognized revenue over the service period.

-
-
-

The Revenue Recognition module automates this for invoices generated by Kill Bill:

-
-
-
    -
  • -

    It creates a revenue schedule for each eligible invoice item as soon as the invoice is generated.

    -
    • -
  • -

    It splits the schedule into dated revenue entries, either one per day of the service period or a single entry for one-time charges.

    -
    • -
  • -

    A background process marks entries as recognized once their date is reached.

    -
    • -
  • -

    Every entry belongs to an accounting period (a calendar month), which you can close at month-end and reopen if needed.

    -
    • -
  • -

    Reports show recognized and deferred revenue by period, by currency, by plan and by recognition method.

    -
    • -
-
-
-

The module answers questions such as:

-
-
-
    -
  • -

    How much of what we invoiced has been earned so far, and how much is still deferred?

    -
    • -
  • -

    How much revenue was recognized in March?

    -
    • -
  • -

    Which schedules does a given account or subscription have, and where does each one stand?

    -
    • -
-
-
-
-
-

Note: The module calculates and reports revenue from billing data. It does not post entries to a general ledger and does not export journals. Whether its output meets a particular accounting standard is for your finance team to determine.

-
-
-
-
-
-
-

Key Features

-
-
-

| Feature | Description | -|---------|-------------| -| Automatic revenue schedules | A schedule is created for every eligible invoice item when the invoice is generated. No manual setup is required. | -| Two recognition methods | Straight-line (daily) for recurring and usage charges; immediate for fixed (one-time) and external charges. | -| Daily recognition | A background process recognizes all entries whose date has been reached. By default it runs once a day. | -| Monthly accounting periods | Periods named YYYY-MM are created automatically as revenue entries are generated. You can also create periods yourself. | -| Period close and reopen | Close a month once all of its revenue has been recognized; reopen it if you need to. | -| Adjustment handling | Invoice item adjustments, cancellation credits and standalone account credits are reflected in the affected schedules. | -| Schedule lookup | Look up schedules by invoice item or schedule ID, or list them with filters such as account, subscription, plan, currency and status. | -| Revenue reports | Period summary, per-currency period summary, revenue waterfall, revenue by plan and recognition rate. |

-
-
-

Before you begin

-
-

Revenue recognition is disabled by default. Your Aviate administrator enables it in the plugin configuration:

-
-
-

| Property | Default | Description | -|----------|---------|-------------| -| com.killbill.billing.plugin.aviate.enableRevenueRecognition | false | Set to true to create revenue schedules for new invoices and to start the daily recognition process. | -| com.killbill.billing.plugin.aviate.revenueRecognition.delaySeconds | 86400 (one day) | How often the recognition process runs, in seconds. |

-
-
-

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

-
-
-
-
-
-

Accounting Periods

-
-
-

An accounting period groups revenue entries by calendar month. Periods are identified by name, in the format YYYY-MM (for example 2026-04).

-
-
-

How periods are created

-
-
    -
  • -

    Automatically. When Aviate creates revenue entries for an invoice item, it creates any monthly period that does not already exist, from the first to the last day of that month.

    -
    • -
  • -

    Manually. You can create a period ahead of time by giving it a name, a start date and an end date.

    -
    • -
-
-
-

Every revenue entry is assigned to the period named after the month of its date. For example, an entry dated 2026-04-17 belongs to period 2026-04. When you create a period manually, use the same YYYY-MM name with the first and last day of the month. A period with any other name receives no revenue entries.

-
-
-
-

Supported operations

-
-

| Operation | What it does | -|-----------|--------------| -| Create | Creates a period with a name, start date and end date. The name must be unique, and the end date cannot be before the start date. | -| List | Lists all periods. Can be filtered to only open or only closed periods. | -| View | Shows one period: its dates, whether it is closed, and when and by whom it was closed. | -| Close | Closes an open period. Rejected if the period still contains unrecognized revenue entries, unless you force the close. | -| Reopen | Reopens a closed period. Its unrecognized entries become eligible for recognition again. | -| Summary | Shows recognized and deferred revenue and the number of entries in the period, for all currencies combined or per currency. |

-
-
-
-

Closing a period

-
-

To close a period:

-
-
-
    -
  • -

    The period must exist and must not already be closed.

    -
    • -
  • -

    All revenue entries dated in that period must already be recognized. Otherwise the close is rejected with a message like Cannot close period 2026-04: 12 unrecognized entries remain.

    -
    • -
  • -

    You can override this check with the force option. Use it when you have reviewed the remaining entries and still want to close the month. For a common case where this is needed, see [Cancellations and adjustments](#cancellations-and-adjustments).

    -
    • -
-
-
-

When a period is closed:

-
-
-
    -
  • -

    The date and the user who closed it are recorded.

    -
    • -
  • -

    The daily recognition process no longer recognizes any remaining unrecognized entries in that period.

    -
    • -
  • -

    Aviate does not create revenue entries for new invoice items whose service dates fall in that period (see [Closed periods](#closed-periods)).

    -
    • -
-
-
-
-

Reopening a period

-
-

Only a closed period can be reopened. 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.

-
-
-
-
-
-

Revenue Recognition Process

-
-
-

1. Schedule creation (when an invoice is generated)

-
-

When Kill Bill generates an invoice, Aviate examines each invoice item and creates one revenue schedule per eligible item:

-
-
-

| Invoice item type | Recognition method | How the amount is spread | -|-------------------|--------------------|--------------------------| -| Recurring | Straight-line | Evenly, one entry per day of the service period | -| Usage | Straight-line | Evenly, one entry per day of the service period | -| Fixed (one-time) | Immediate | One entry for the full amount on the service start date | -| External charge | Immediate | One entry for the full amount on the service start date |

-
-
-

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.

-
-
-

Each schedule records:

-
-
-
    -
  • -

    The invoice, invoice item, account, subscription, plan and phase it came from.

    -
    • -
  • -

    Its currency and total amount.

    -
    • -
  • -

    Its service period and recognition method.

    -
    • -
  • -

    Its running recognized and deferred amounts. At creation, the full amount is deferred.

    -
    • -
  • -

    Whether it is closed, meaning fully recognized or ended early by an adjustment.

    -
    • -
-
-
-
-

2. Straight-line calculation

-
-

For straight-line schedules:

-
-
-
    -
  • -

    The service period runs from the item’s start date up to, but not including, its end date. A 1 January to 1 February period is 31 days.

    -
    • -
  • -

    The daily amount is the total divided by the number of days, rounded to nine decimal places.

    -
    • -
  • -

    The last day takes any rounding difference, so the entries always add up exactly to the schedule total.

    -
    • -
-
-
-
-

3. Daily recognition

-
-

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

-
-
-
    -
  • -

    Recognizes every unrecognized entry dated on or before the current date (UTC) in an open period, including entries dated today.

    -
    • -
  • -

    Updates each affected schedule’s recognized and deferred amounts.

    -
    • -
  • -

    Closes a schedule once its full amount has been recognized.

    -
    • -
-
-
-
-

Recognizing revenue for a specific month

-
-

There is no customer-facing operation that runs recognition on demand for a chosen date or month. Revenue for a month is recognized by the regular runs as its days pass. All of a month’s entries have been processed once a run has taken place on or after the last day of that month.

-
-
-

The month-end workflow is:

-
-
-
    -
  1. -

    Wait for a recognition run on or after the last day of the month.

    -
    2. -
  2. -

    Review the month with the period summary.

    -
    3. -
  3. -

    Close the period.

    -
    4. -
-
-
-

See [Close a month](#close-a-month) for the steps.

-
-
-
-
-
-

Business Rules and Constraints

-
-
-

Recognition rules

-
-
    -
  • -

    The recognition method depends only on the invoice item type. It cannot be configured per plan, product or customer.

    -
    • -
  • -

    Recognition follows the service dates on the invoice item, not the invoice date or the payment date. Revenue is recognized whether or not the invoice has been paid.

    -
    • -
  • -

    Revenue is always assigned to calendar months. Custom fiscal calendars (for example 4-4-5 periods) are not supported.

    -
    • -
-
-
-
-

Closed periods

-
-
    -
  • -

    Closing a period does not block billing. Invoices, credits, adjustments and payments dated in a closed period are still accepted by Kill Bill.

    -
    • -
  • -

    If a new invoice item has service dates in a closed period, Aviate does not create its revenue entries. If you expect back-dated invoices, reopen the affected period before the invoice is generated.

    -
    • -
  • -

    Adjustments and credits processed after a period is closed still update the affected schedules (see below).

    -
    • -
-
-
-
-

Cancellations and adjustments

-
-

When an invoice item is reduced after its schedule exists, for example by an item adjustment or by the credit Kill Bill issues when a subscription is cancelled or changed mid-period:

-
-
-
    -
  • -

    If the item still has deferred revenue, Aviate records a reversal entry for the adjustment amount, ends the schedule at the adjustment date and closes it. Days after that date are not recognized.

    -
    • -
  • -

    If the item’s revenue has already been fully recognized, the schedule is not changed and no reversal is recorded.

    -
    • -
  • -

    The days that were not recognized remain in their month as unrecognized entries. Closing a month that contains a mid-period cancellation or adjustment therefore requires the force option.

    -
    • -
  • -

    Reversal entries are not assigned to an accounting period, so they do not appear in period summaries or in a waterfall that has a start period.

    -
    • -
-
-
-
-

Account credits

-
-
    -
  • -

    A credit created on its own, outside an invoice that also contains charges, reduces the deferred revenue of the account’s open schedules. You cannot choose which schedules a credit is applied to.

    -
    • -
  • -

    Credits that appear on the same invoice as recurring, usage, fixed or external charges are not treated as revenue adjustments and do not change any schedule.

    -
    • -
-
-
-
-

Reports

-
-

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

-
-
-

| Report | Built from | Currency handling | -|--------|-----------|-------------------| -| Period summary | Revenue entries in the period | All currencies added together | -| Period currency summary | Revenue entries in the period | One row per currency | -| Revenue waterfall | Revenue entries, by period | One row per period and currency | -| Revenue by plan | Schedule totals | All currencies added together | -| Recognition rate | Schedule totals, by recognition method | All currencies added together |

-
-
-
    -
  • -

    In entry-based reports, "deferred" is the total of entries not yet recognized. This includes entries left unrecognized after a cancellation or adjustment.

    -
    • -
  • -

    For tenants that bill in more than one currency, use the period currency summary or the waterfall to avoid adding amounts in different currencies together.

    -
    • -
-
-
-
-

Access and permissions

-
-
    -
  • -

    All revenue operations apply to the tenant identified by the Kill Bill API key and secret on the request.

    -
    • -
  • -

    When role-based access control is enabled in Aviate, any authenticated role can read revenue data. Creating, closing and reopening periods requires one of the roles finance_admin, finance_vp, system_admin, admin or super_admin.

    -
    • -
-
-
-
-

Data you cannot edit

-
-

Revenue schedules and entries are derived from invoices. You cannot create, edit or delete them directly. To change revenue, change the underlying invoice, for example with an item adjustment.

-
-
-
-
-
-

Usage Instructions

-
-
-

All operations are available through the Aviate REST API under:

-
-
-
-
http://<killbill-host>:8080/plugins/aviate-plugin/v1/revenue
-
-
-
-

Every request needs:

-
-
-
    -
  • -

    Authorization: Bearer ${ID_TOKEN} (your Aviate token)

    -
    • -
  • -

    X-killbill-apiKey and X-killbill-apisecret (your tenant credentials)

    -
    • -
-
-
-

Parameters are passed in the query string. As with other Aviate actions, send POST requests with Content-Type: application/json and an empty JSON body ({}).

-
-
-

The examples below use these shell variables:

-
-
-
-
export AVIATE=http://127.0.0.1:8080/plugins/aviate-plugin
-export API_KEY=<your-api-key>
-export API_SECRET=<your-api-secret>
-
-
-
-

Look up revenue schedules

-
-

List schedules with any combination of filters:

-
-
-

| Query parameter | Description | -|-----------------|-------------| -| accountId | Schedules of one account | -| subscriptionId | Schedules of one subscription | -| planName | Schedules for one plan | -| currency | Schedules in one currency, for example USD | -| closed | true for closed schedules, false for open ones | -| servicePeriodStart | Schedules whose service period starts on or after this date (YYYY-MM-DD) | -| offset, limit | Paging. limit defaults to and cannot exceed 1000. |

-
-
-

Results are returned newest first.

-
-
-
-
curl -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     "${AVIATE}/v1/revenue/schedules?accountId=${ACCOUNT_ID}&closed=false&limit=50" | jq .
-
-
-
-

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

-
-
-
-
curl -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     "${AVIATE}/v1/revenue/${INVOICE_ITEM_ID}/schedule" | jq .
-
-
-
-

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

-
-
-
-
curl -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     "${AVIATE}/v1/revenue/schedules/${SCHEDULE_ID}" | jq .
-
-
-
-

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

-
-
-
-
curl -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     "${AVIATE}/v1/revenue/${SCHEDULE_ID}/entriesPerSchedule" | jq .
-
-
-
-
-

Manage accounting periods

-
-

Create a period. All three parameters are required. A successful request returns 201 Created.

-
-
-
-
curl -X POST \
-     -H'Content-Type: application/json' \
-     -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     -d '{}' \
-     "${AVIATE}/v1/revenue/periods?periodName=2026-05&startDate=2026-05-01&endDate=2026-05-31"
-
-
-
-

List periods. Add closed=true or closed=false to filter.

-
-
-
-
curl -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     "${AVIATE}/v1/revenue/periods?closed=false" | jq .
-
-
-
-

View one period:

-
-
-
-
curl -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     "${AVIATE}/v1/revenue/periods/2026-04" | jq .
-
-
-
-
-

Close a month

-
-
    -
  1. -

    Check that the month has been processed. A recognition run must have taken place on or after the last day of the month.

    -
    2. -
  2. -

    Review the period summary. It returns the period name, the recognized amount, the deferred (not yet recognized) amount and the number of entries.

    -
    -
    -
    ```
-curl -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     "${AVIATE}/v1/revenue/periods/2026-04/summary" | jq .
-```
    -
    -
    -
    -
    -
    For figures per currency, use `currencySummary` instead:
    -
    -
    -
    -
    -
    ```
-curl -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     "${AVIATE}/v1/revenue/periods/2026-04/currencySummary" | jq .
-```
    -
    -
    -
    3. -
  3. -

    Close the period. A successful close returns 204 No Content.

    -
    -
    -
    ```
-curl -X POST \
-     -H'Content-Type: application/json' \
-     -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     -d '{}' \
-     "${AVIATE}/v1/revenue/periods/2026-04/close"
-```
    -
    -
    -
    4. -
  4. -

    If the close is rejected because unrecognized entries remain, look at the schedules involved (for example, those closed early by a cancellation). If you still want to close the month, repeat the request with force=true:

    -
    -
    -
    ```
-curl -X POST \
-     -H'Content-Type: application/json' \
-     -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     -d '{}' \
-     "${AVIATE}/v1/revenue/periods/2026-04/close?force=true"
-```
    -
    -
    -
    5. -
-
-
-
-

Reopen a month

-
-

A successful reopen returns 204 No Content. The request is rejected if the period does not exist or is not closed.

-
-
-
-
curl -X POST \
-     -H'Content-Type: application/json' \
-     -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     -d '{}' \
-     "${AVIATE}/v1/revenue/periods/2026-04/reopen"
-
-
-
-
-

Run reports

-
-

Revenue waterfall. Recognized and deferred revenue per period and currency. All parameters are optional: startPeriod and endPeriod (YYYY-MM, inclusive) and currency.

-
-
-
-
curl -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     "${AVIATE}/v1/revenue/reports/waterfall?startPeriod=2026-01&endPeriod=2026-06&currency=USD" | jq .
-
-
-
-

Revenue by plan. Total, recognized and deferred amounts and the number of schedules per plan, across the whole tenant. Takes no parameters.

-
-
-
-
curl -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     "${AVIATE}/v1/revenue/reports/by-plan" | jq .
-
-
-
-

Recognition rate. 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.

-
-
-
-
curl -H"Authorization: Bearer ${ID_TOKEN}" \
-     -H"X-killbill-apiKey: ${API_KEY}" \
-     -H"X-killbill-apisecret: ${API_SECRET}" \
-     "${AVIATE}/v1/revenue/reports/recognition-rate" | jq .
-
-
-
-
-
-
-

Examples

-
-
-

Example 1: Monthly subscription

-
-

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

-
-
-
    -
  • -

    Aviate creates a straight-line schedule with a total of 31.00, all deferred.

    -
    • -
  • -

    The service period is 31 days, so Aviate creates 31 entries of 1.00, dated 2026-01-01 to 2026-01-31, all in period 2026-01.

    -
    • -
  • -

    Each daily run recognizes the entries dated up to that day. After the run on 2026-01-10, 10.00 is recognized and 21.00 is deferred.

    -
    • -
  • -

    After the run on 2026-01-31, the full 31.00 is recognized and the schedule is closed.

    -
    • -
-
-
-
-

Example 2: Quarterly subscription spanning three months

-
-

A customer is invoiced USD 90.00 for a quarterly plan covering 2026-01-01 to 2026-04-01, which is 90 days. The daily amount is 1.00, so the revenue falls into three periods:

-
-
-

| Period | Days | Revenue | -|--------|------|---------| -| 2026-01 | 31 | 31.00 | -| 2026-02 | 28 | 28.00 | -| 2026-03 | 31 | 31.00 | -| Total | 90 | 90.00 |

-
-
-

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

-
-
-
-

Example 3: Rounding

-
-

A customer is invoiced USD 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.

    -
    • -
-
-
-
-

Example 4: One-time setup fee

-
-

A customer is invoiced a fixed USD 250.00 setup fee with a service start date of 2026-04-15.

-
-
-
    -
  • -

    Aviate creates an immediate schedule with one entry of 250.00 dated 2026-04-15, in period 2026-04.

    -
    • -
  • -

    The first recognition run on or after 2026-04-15 recognizes the full amount and closes the schedule.

    -
    • -
-
-
-
-

Example 5: Month-end close

-
-

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

-
-
-
    -
  1. -

    The daily run on 2026-04-30 or later has recognized all April entries.

    -
    2. -
  2. -

    GET /v1/revenue/periods/2026-04/summary shows the recognized total for April with a deferred amount of 0.

    -
    3. -
  3. -

    POST /v1/revenue/periods/2026-04/close returns 204 No Content.

    -
    4. -
  4. -

    GET /v1/revenue/periods?closed=true now lists 2026-04 with the closing date and user.

    -
    5. -
-
-
-

If a subscription had been cancelled in the middle of April, its remaining April days would still be unrecognized. Step 3 would be rejected with Cannot close period 2026-04: N unrecognized entries remain. After review, the team would close the month with force=true.

-
-
-
-

Example 6: Mid-period cancellation

-
-

A USD 31.00 schedule covers 2026-01-01 to 2026-02-01. By 2026-01-15, 15.00 has been recognized. The subscription is then cancelled with effect from 2026-01-16, and Kill Bill credits the unused 16.00.

-
-
-
    -
  • -

    Aviate records a reversal entry of −16.00, ends the schedule on 2026-01-16 and closes it.

    -
    • -
  • -

    Days after 2026-01-16 are not recognized.

    -
    • -
  • -

    The unrecognized January days stay in period 2026-01. Closing January therefore requires force=true.

    -
    • -
  • -

    The reversal entry has no accounting period, so it does not appear in the January period summary.

    -
    • -
-
-
-
-
-
- - - - \ No newline at end of file diff --git a/userguide/tutorials/email-notification-plugin.html b/userguide/tutorials/email-notification-plugin.html deleted file mode 100644 index 281fd4ba6..000000000 --- a/userguide/tutorials/email-notification-plugin.html +++ /dev/null @@ -1,1594 +0,0 @@ - - - - - - - -Email Notification Plugin - - - - - - -
-
-
-
-

As the name implies, the email notification plugin is a plugin that sends out emails when certain events occur. This document covers how to install, test, and use this plugin, with support for both SMTP and AWS SES for sending email notifications.

-
-

Prerequisites

-
-
    -
  • -

    Ensure that you have Kill Bill, Kaui, and the database set up as explained in the Getting Started Guide.

    -
    • -
  • -

    Ensure that you have cURL installed. If you are on Windows, we recommend that you use Git Bash to run the cURL commands.

    -
    • -
  • -

    If you plan to use AWS SES, obtain your AWS SES credentials (access key and secret key) and ensure that the IAM user has the ses:SendEmail permission.

    -
    • -
-
-
-
-
-

Overview

-
-
-

The email notification plugin is a notification plugin. It listens to Kill Bill Events and sends emails accordingly.

-
-
-

Currently, the email notification plugin supports the following events:

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Event TypeEmail Description

INVOICE_CREATION

The customer will receive an email informing them that a new invoice is available.

INVOICE_NOTIFICATION

The customer will receive an email about upcoming invoices (The time at which to send the email can be configured through the org.killbill.invoice.dryRunNotificationSchedule property as specified in the Kill Bill Configuration Guide).

INVOICE_PAYMENT_SUCCESS

The customer will receive an email after each successful payment or refund.

INVOICE_PAYMENT_FAILED

The customer will receive an email after each failed payment.

SUBSCRIPTION_CANCEL

The customer will receive an email at the time a subscription was requested to be canceled and/or at the effective date of the subscription cancellation.

-
-

In addition, it can be extended to to handle other types of events as well. This is explained in the "Configuring the Plugin for Additional Events" section below.

-
-
-

To send an email the following is required:

-
-
-
    -
  • -

    The tenant or account must be configured to permit such event(s). This is explained in the "Plugin Configuration" section below.

    -
    • -
  • -

    The account for which the emails need to be sent must have certain fields set. This is explained in the "Account Configuration" section below.

    -
    • -
-
-
-
-
-

Plugin Installation

-
-
-

The email notification plugin can easily be installed via the Aviate UI. Refer to this doc for a detailed demo.

-
-
-

Alternatively, the plugin can also be installed either via Kaui or KPM as explained in the Plugin Installation Guide.

-
-
-

For example, to install the plugin via KPM, you can run the following command:

-
-
-
-
kpm install_java_plugin email-notifications --destination=<path_to_install_plugin>
-
-
-
-

If you would like to make changes to the plugin, you can clone the plugin code, build and deploy it as explained here.

-
-
-
-
-

Database Configuration

-
-
-

The email-notification-plugin requires some additional database tables. To create these tables, please follow the stes given below:

-
-
-
    -
  1. -

    Connect to the Kill Bill database.

    -
    2. -
  2. -

    Run the email-notification-plugin DDL.

    -
    3. -
-
-
-
-
-

Plugin Configuration

-
-
-

In order to use the email notification plugin, you need to configure either SMTP or AWS SES settings. Below are the steps to configure both:

-
-
-

AWS SES Configuration

-
-

To enable AWS SES for email notifications, add the following properties into killbill.properties. The default sender’s email must be verified in AWS SES.

-
-
-
-
org.killbill.email.notification.via.ses=true
-org.killbill.mail.from=<Default sender's email>
-org.killbill.aws.region=<AWS region, default region is us-east-1>
-
-
-
-

AWS SES requires authentication for sending emails. System-wide environment variables can be configured for all users by appending them to the /etc/environment file. Open the /etc/environment file in a text editor with root privileges, set the following variables:

-
-
-
-
AWS_ACCESS_KEY_ID=<AWS access key ID>
-AWS_SECRET_ACCESS_KEY=<AWS access secret>
-
-
-
-

Reboot the system to apply the changes.

-
-
- - - - - -
-
Note
-		 -Note: Ensure that the credentials used have the necessary permissions, specifically ses:SendEmail, on the resource arn:aws:ses:<region>:<account>:identity/<sender’s email>. -
-
-
-
-

SMTP Configuration

-
-

A tenant needs to be configured with the SMTP properties required for sending emails. Additionally, the tenant can also be configured with the events for which emails should be sent. In addition to the per-tenant configuration, the plugin also allows a more granular account-level configuration for the set of emails to be sent for the particular account. Thus, either the tenant or the account needs to be configured with the events for which the email needs to be sent.

-
-
-

The configuration can easily be done via the Aviate UI Refer to this doc for a detailed demo.

-
-
-

Alternatively, the tenant configuration can also be done or via the Add a per-tenant configuration for a plugin endpoint as explained below:

-
-
-

Configure the tenant using the following cURL command (Replace <events> with a comma-separated list of the events for which the emails need to be sent. For example, to configure the tenant to send emails for INVOICE_CREATION and INVOICE_PAYMENT_SUCCESS, specify org.killbill.billing.plugin.email-notifications.defaultEvents=INVOICE_CREATION,INVOICE_PAYMENT_SUCCESS):

-
-
-
-
curl -v \
-     -X POST \
-     -u admin:password \
-     -H 'X-Killbill-ApiKey: bob' \
-     -H 'X-Killbill-ApiSecret: lazar' \
-     -H 'X-Killbill-CreatedBy: admin' \
-     -H 'Content-Type: text/plain' \
-     -d 'org.killbill.billing.plugin.email-notifications.defaultEvents=<events>
-org.killbill.billing.plugin.email-notifications.smtp.host=127.0.0.1
-org.killbill.billing.plugin.email-notifications.smtp.port=25
-org.killbill.billing.plugin.email-notifications.smtp.useAuthentication=true
-org.killbill.billing.plugin.email-notifications.smtp.userName=uuuuuu
-org.killbill.billing.plugin.email-notifications.smtp.password=zzzzzz
-org.killbill.billing.plugin.email-notifications.smtp.useSSL=false
-org.killbill.billing.plugin.email-notifications.smtp.sendHTMLEmail=true
-org.killbill.billing.plugin.email-notifications.smtp.defaultSender=xxx@yyy.com' \
-http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-email-notifications
-
-
-
- - - - - -
-
Note
-		 -Note: On Windows systems, multiline cURL commands like the one above do not run property when cURL is used on the standard windows command prompt. So, we recommend using either Git Bash or Postman as explained here. -
-
-
-
-

SMTP Server Notes

-
-

In order to be able to use the email notification plugin to send emails, a local SMTP server is required.

-
-
-

We typically use the namshi/smtp docker image as follows to start a local SMTP server on port 25:

-
-
-
-
docker run -tid --name smtp_server -p 25:25  -e DISABLE_IPV6=true namshi/smtp
-
-
-
-

Alternatively, if you would like to use a non-docker based SMTP server, you can use MailSlurper. MailSlurper is a small handy SMTP server that can be useful for development and testing. It can be downloaded and configured as explained in its documentation.

-
-
-
-
-
-

Account Configuration

-
-
-

The account for which emails need to be sent, needs to have the email and locale fields set. In addition, the default email templates used by the notification plugin also require the company, address1, city, state, postalCode, country fields set on the Account.

-
-
-

Thus, ensure that the account is created using the following cURL command (Replace <email_id> with the email id where you would like to receive the email and change values for the other fields as required):

-
-
-
-
curl -v \
-    -X POST \
-    -u admin:password \
-    -H "X-Killbill-ApiKey: bob" \
-    -H "X-Killbill-ApiSecret: lazar" \
-    -H "Content-Type: application/json" \
-    -H "Accept: application/json" \
-    -H "X-Killbill-CreatedBy: demo" \
-    -H "X-Killbill-Reason: demo" \
-    -H "X-Killbill-Comment: demo" \
-    -d '{ "name": "John Doe", "email": "<email_id>", "currency": "USD", "company": "Acme Corporation", "locale":"en_US", "address1": "57 Academy Drive","city": "Oak Creek","state": "WI","postalCode": "53154", "country": "US"}' \
-"http://127.0.0.1:8080/1.0/kb/accounts"
-
-
-
-

Configure Events

-
-

Configure the account using the following cURL command (Replace {accountId} with the id of the account for which emails need to be sent and <events> with a comma-separated list of the events for which the emails need to be sent. For example, to configure the account to send emails for INVOICE_CREATION and INVOICE_PAYMENT_SUCCESS, specify "INVOICE_CREATION", "INVOICE_PAYMENT_SUCCESS"):

-
-
-
-
curl -v \
-     -X POST \
-     -u admin:password \
-     -H 'X-Killbill-ApiKey: bob' \
-     -H 'X-Killbill-ApiSecret: lazar' \
-     -H 'X-Killbill-CreatedBy: admin' \
-     -H 'Content-Type: application/json' \
-     -d '[<events>]' \
-    http://127.0.0.1:8080/plugins/killbill-email-notifications/v1/accounts/{accountId}
-
-
-
-

Note that either the tenant or the account should be configured with the events for which emails need to be sent, otherwise, emails will not be sent. Some scenarios for this:

-
-
-
    -
  1. -

    If a tenant is configured with some events, but the account is not configured, then emails will be sent based on what is configured at the tenant level.

    -
    2. -
  2. -

    If a tenant is not configured with any events but the account is configured with events, then emails will be sent based on what is configured at the account level.

    -
    3. -
  3. -

    If both tenant and account are configured with separate events, emails will be sent based on the events configured for both.

    -
    4. -
-
-
-
-
-
-

Testing the Plugin

-
-
-

Once the plugin is installed and configured as explained above, it can be used for sending emails. You can verify that the plugin is working correctly by following the steps given below:

-
-
-
    -
  1. -

    If you’re using SMTP, start a local SMTP server as explained in the "SMTP Server Notes" section. Otherwise, if you’re using AWS SES, make sure it’s configured as explained in the "Plugin Configuration" section.

    -
    2. -
  2. -

    Ensure that Kill Bill is running either in _standalone mode or in Tomcat.

    -
    3. -
  3. -

    Create a tenant as follows (specify the required apiKey and apiSecret):

    -
    -
    -
    curl -v \
-    -X POST \
-    -u admin:password \
-    -H "Content-Type: application/json" \
-    -H "Accept: application/json" \
-    -H "X-Killbill-CreatedBy: demo" \
-    -H "X-Killbill-Reason: demo" \
-    -H "X-Killbill-Comment: demo" \
-    -d '{ "apiKey": "bob", "apiSecret": "lazar"}' \
-    "http://127.0.0.1:8080/1.0/kb/tenants"
    -
    -
    -
    4. -
  4. -

    Create an account as follows (Replace <email_id> with the email id where you would like to receive the email and change values for the other fields as required):

    -
    -
    -
    curl -v \
-    -X POST \
-    -u admin:password \
-    -H "X-Killbill-ApiKey: bob" \
-    -H "X-Killbill-ApiSecret: lazar" \
-    -H "Content-Type: application/json" \
-    -H "Accept: application/json" \
-    -H "X-Killbill-CreatedBy: demo" \
-    -H "X-Killbill-Reason: demo" \
-    -H "X-Killbill-Comment: demo" \
-    -d '{ "name": "John Doe", "email": "<email_id>", "currency": "USD", "company": "Acme Corporation", "locale":"en_US", "address1": "57 Academy Drive","city": "Oak Creek","state": "WI","postalCode": "53154", "country": "US"}' \
-"http://127.0.0.1:8080/1.0/kb/accounts"
    -
    -
    -
    5. -
  5. -

    If successful, the command above returns a Location header like http://127.0.0.1:8080/1.0/kb/accounts/eda3e357-20a1-456d-a9b3-b39ca3db8020. Copy the account_id in the header (eda3e357-20a1-456d-a9b3-b39ca3db8020 in this case) and save it for future use.

    -
    6. -
  6. -

    If you’re using SMTP, configure the tenant as specified in the "Plugin Configuration" section above with INVOICE_CREATION and INVOICE_PAYMENT_SUCCESS events.

    -
    7. -
  7. -

    Add a payment method as follows (replace <account_id> with the account id obtained above):

    -
    -
    -
    curl -v \
-    -X POST \
-    -u admin:password \
-    -H "X-Killbill-ApiKey: bob" \
-    -H "X-Killbill-ApiSecret: lazar" \
-    -H "Content-Type: application/json" \
-    -H "Accept: application/json" \
-    -H "X-Killbill-CreatedBy: demo" \
-    -H "X-Killbill-Reason: demo" \
-    -H "X-Killbill-Comment: demo" \
-    -d '{ "accountId": "<account_id>", "pluginName": "__EXTERNAL_PAYMENT__"}' \
-    "http://127.0.0.1:8080/1.0/kb/accounts/<account_id>/paymentMethods"
    -
    -
    -
    8. -
  8. -

    If successful, the command above returns a Location header like -http://127.0.0.1:8080/1.0/kb/paymentMethods/c2ff0040-7c5b-48bf-9685-a4c57501535f. Copy the payment_method_id in the header (c2ff0040-7c5b-48bf-9685-a4c57501535f in this case) and save it for future use.

    -
    9. -
  9. -

    Set the payment method as default as follows (Replace <account_id> and <payment_method_id> with the values obtained above):

    -
    -
    -
    curl -v \
-    -X PUT \
-    -u admin:password \
-    -H "X-Killbill-ApiKey: bob" \
-    -H "X-Killbill-ApiSecret: lazar" \
-    -H "Content-Type: application/json" \
-    -H "Accept: application/json" \
-    -H "X-Killbill-CreatedBy: demo" \
-    -H "X-Killbill-Reason: demo" \
-    -H "X-Killbill-Comment: demo" \
-    "http://127.0.0.1:8080/1.0/kb/accounts/<account_id>/paymentMethods/<payment_method_id>/setDefault"
    -
    -
    -
    10. -
  10. -

    Create a external charge to trigger an invoice as follows (Replace <account_id> with the account_id obtained above):

    -
    -
    -
    curl -v \
-    -X POST \
-    -u admin:password \
-    -H "X-Killbill-ApiKey: bob" \
-    -H "X-Killbill-ApiSecret: lazar" \
-    -H "Content-Type: application/json" \
-    -H "Accept: application/json" \
-    -H "X-Killbill-CreatedBy: demo" \
-    -H "X-Killbill-Reason: demo" \
-    -H "X-Killbill-Comment: demo" \
-    -d '[ { "accountId": "<account_id>", "description": "My charge", "amount": 50, "currency": "USD" }]'    \
-    "http://127.0.0.1:8080/1.0/kb/invoices/charges/<account_id>?autoCommit=true"
    -
    -
    -
    11. -
  11. -

    Confirm that an email is sent for the invoice and successful payment.

    -
    12. -
-
-
-

Note that you can also use Kaui for executing steps 2-9 above.

-
-

Template and Resource Configuration

-
-

The email notification plugin uses Mustache templates for generating emails. This section explains how custom email templates can be configured.

-
-
-

There are three things you can customize for a given email:

-
-
-
    -
  • -

    A template: This constitutes the body of the email. It includes static text as well as variables which are replaced at runtime by the [mustache](https://mustache.github.io/) engine.

    -
    • -
  • -

    A resource file: This contains key-value pairs used to replace translation variables in a template, corresponding to a locale. See "Resources Overview" below.

    -
    • -
  • -

    Branding information: Company details, appearance/style, and logo, which can be set as a tenant-wide default (shared with invoice templates) and optionally overridden per email template type. See "Branding Overview" below.

    -
    • -
-
-
-

Templates Overview

-
-

An email template contains the body of an email. In addition to static text, it contains some variables which are replaced at runtime by the mustache engine.

-
-
-

The email notification plugin comes with some default templates. However, users can also upload their custom templates.

-
-
-

The email notification plugin uses one template per locale and per type (as opposed to one template per type with an additional set of translation string bundles for each locale). So, for example, the INVOICE_CREATION event can have templates like INVOICE_CREATION_en_US, INVOICE_CREATION_fr_FR, and so on. When an INVOICE CREATION email needs to be sent for a user, the user’s locale is checked and the corresponding template is used. The default templates are available only for the en_US locale, however, users can upload templates for other locales if required.

-
-
-
-

Resources Overview

-
-

In addition to templates, the email notification plugin requires a resource file. This resource file contains key-value pairs which can be used to replace variables in a template. The email notification plugin comes with a default resource file that contains key-value pairs for the variables in the default templates.

-
-
-

Unlike email templates, all the events have a single resource file. However, different locales can have different resource files. This allows having string translations in different languages, (like different translations for the catalog product names). So for example, you can have different resource files like Translation_en_US.properties, Translation_fr_FR.properties, and so on. When an email needs to be sent for a user, the user’s locale is checked and the corresponding resource file is used to replace the variables in the template.

-
-
-

The default resource file is available only for the en_US locale. Users can add additional key-value pairs to this resource file as well as add new resource files for different locales.

-
-
-
-

Branding Overview

-
-

In addition to the template and resource file, branding information — company details, appearance/style, and logo — can also be customized. This is read from the tenant_kvs table and can be set as a tenant-wide default shared across invoices and emails, and optionally overridden per email template type. See "Managing Templates, Translations & Branding via Aviate" and "Upload Branding Information" below.

-
-
-
-
-
-

Managing Templates, Translations & Branding via Aviate

-
-
-

While templates, translations, and branding information can all be uploaded directly via the Kill Bill API, Aviate — the premium UI/plugin layer on top of Kill Bill — is the recommended way to manage all three, since it provides a guided experience with a live email preview, inheritance indicators, and inline validation.

-
-
- - - - - -
-
Note
-		 -Before you can configure templates, translations, or branding via Aviate, the Kill Bill instance must first be added as a deployment. See Aviate Deployment Management for details. -
-
-
-

Organization-level branding

-
-

Organization-level branding (company information and appearance) is shared between invoice and email templates, and is configured once. See Organization-level branding in the Invoice Templates document.

-
-
-
-

Email-template-level template and branding

-
-

Under Configuration → Email → Templates, configure a given email template (e.g. Invoice Creation) as follows:

-
-
-
    -
  1. -

    Select the desired template type from the drop-down (e.g. Invoice Creation).

    -
    2. -
  2. -

    Override company information and appearance for this template only, if required. Fields are pre-filled from the organization-level settings, with an indicator showing which are inherited versus overridden.

    -
    3. -
  3. -

    Customize style details such as text color, table heading background/text color, and table border color.

    -
    4. -
  4. -

    Use the live email preview panel to confirm your changes render as expected.

    -
    5. -
  5. -

    Click Save Template to save the changes.

    -
    6. -
  6. -

    Advanced users can also edit the underlying mustache template directly via Advanced View, instead of the structured fields in steps 2–3. This is not recommended unless you are familiar with the mustache template engine.

    -
    7. -
-
-
-

Repeat this for each email template type you want to customize.

-
-
-
-

Translations

-
-

Under Configuration → Email → Translation, configure translations as follows:

-
-
-
    -
  1. -

    Select the desired language from the drop-down.

    -
    2. -
  2. -

    Modify the translation strings, organized by category (e.g. Invoice, Payment).

    -
    3. -
  3. -

    Use the Preview drop-down to see how the translations render for a specific email template type.

    -
    4. -
  4. -

    Click Save Translation to save the changes.

    -
    5. -
-
-
-
-
-
-

Managing Templates, Translations & Branding via API

-
-
-

If you are not using Aviate, or need to script/automate these uploads, you can manage the template, resource file, and branding directly through the Kill Bill API, as described below.

-
-
-

Template/Translation Resource Keys

-
-

Each email template and the translation resource is assigned a key. To upload a custom email template/translation resource, its key needs to be specified.

-
-
-

The following table provides details about the template/translation resource keys (assuming that the locale is en_US):

-
- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Template TypeTemplate KeyTemplate DescriptionDefault Template

Invoice creation

killbill-email-notifications:INVOICE_CREATION_en_US

Template for the email that will be sent when an invoice is created

InvoiceCreation.mustache

Upcoming invoices

killbill-email-notifications:UPCOMING_INVOICE_en_US

Template for the email that will be sent when an invoice is due

UpcomingInvoice.mustache

Successful payments

killbill-email-notifications:SUCCESSFUL_PAYMENT_en_US

Template for the email that will be sent when a payment is successful

SuccessfulPayment.mustache

Failed payments

killbill-email-notifications:FAILED_PAYMENT_en_US

Template for the email that will be sent when a payment fails

FailedPayment.mustache

Subscription cancellation (requested date)

killbill-email-notifications:SUBSCRIPTION_CANCELLATION_REQUESTED_en_US

Template for the email that will be sent when a user requests to cancel a subscription

SubscriptionCancellationRequested.mustache

Subscription cancellation (effective date)

killbill-email-notifications:SUBSCRIPTION_CANCELLATION_EFFECTIVE_en_US

Template for the email that will be sent when a subscription is actually cancelled

SubscriptionCancellationEffective.mustache

Payment refunds

killbill-email-notifications:PAYMENT_REFUND_en_US

Template for the email that will be sent when a payment is refunded

PaymentRefund.mustache

Translation strings

killbill-email-notifications:TEMPLATE_TRANSLATION_en_US

Includes all the text values referenced in the templates. Also includes the email subjects using the following keys: -upcomingInvoiceSubject -successfulPaymentSubject -failedPaymentSubject -paymentRefundSubject -subscriptionCancellationRequestedSubject -subscriptionCancellationEffectiveSubject -invoiceCreationSubject

Translation_en.properties

-
-
-

Uploading a Custom Template

-
-

As explained earlier, you can upload per-tenant email templates for various events. Let’s look at an example to upload a template for the next upcoming invoice for a locale en_US:

-
-
-
    -
  1. -

    Create the template /tmp/UpcomingInvoice.mustache:

    -
    -
    -
    *** You Have a New Invoice ***
-
-You have a new invoice from {{text.merchantName}}, due on {{invoice.targetDate}}.
-
-{{#invoice.invoiceItems}}
-{{startDate}} {{planName}} : {{invoice.formattedAmount}}
-{{/invoice.invoiceItems}}
-
-{{text.invoiceAmountTotal}}: {{invoice.formattedBalance}}
-
-{{text.billedTo}}:
-{{account.companyName}}
-{{account.name}}
-{{account.address1}}
-{{account.city}}, {{account.stateOrProvince}} {{account.postalCode}}
-{{account.country}}
-
-If you have any questions about your account, please reply to this email or contact {{text.merchantName}} Support at: {{text.merchantContactPhone}}
    -
    -
    -
    2. -
  2. -

    Upload the template for your tenant:

    -
    -
    -
    curl -v \
--u admin:password \
--H "X-Killbill-ApiKey: bob" \
--H "X-Killbill-ApiSecret: lazar" \
--H 'X-Killbill-CreatedBy: admin' \
--H "Content-Type: text/plain" \
--X POST \
---data-binary @/tmp/UpcomingInvoice.mustache \
-http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/killbill-email-notifications:UPCOMING_INVOICE_en_US
    -
    -
    -
    3. -
  3. -

    If your template uses some additional keys than what are specified in the default translation file, these need to be added to the translation file as explained in the next section.

    -
    4. -
-
-
-
-

Uploading Resource Files

-
-

As explained earlier, you can upload additional resource files for different locales or additional keys in existing resource files. In order to do this, please follow the steps given below:

-
-
-
    -
  1. -

    Check if a resource file already exists for your locale. If so, download the file and if not, create a new file. You can use the default translation template as a reference to create a new file.

    -
    2. -
  2. -

    Add the required properties (key-value pairs) to your file.

    -
    3. -
  3. -

    Upload the new resource file using the following cURL command (Replace <template-name> with the name of the file created in the previous step and <translation_key> with the translation key. For example the translation key for a resource file for the en_US locale will be TEMPLATE_TRANSLATION_en_US):

    -
    -
    -
    curl -v \
--u admin:password \
--H "X-Killbill-ApiKey: bob" \
--H "X-Killbill-ApiSecret: lazar" \
--H 'X-Killbill-CreatedBy: admin' \
--H "Content-Type: text/plain" \
--X POST \
---data-binary @/<template-name>.properties \
-http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/killbill-email-notifications:<translation_key>
    -
    -
    -
    4. -
-
-
-
-

Upload Branding Information

-
-

Branding fields (company info, style, logo) can be set directly using the [per-tenant user key/value endpoint](https://apidocs.killbill.io/tenant.html#add-a-per-tenant-user-key-value), the same mechanism used for invoice template branding.

-
-
-

Organization-level branding (COMPANY_INFO, LOGO_INFO, BRAND_INFO) is shared across invoices and emails — see ["Upload Branding Information"](https://docs.killbill.io/latest/invoice_templates.html#upload-branding-information) in the Invoice Templates document for those keys and example payloads.

-
-
-

To override branding for a specific email template type, use the corresponding EMAIL_TEMPLATE_* key instead:

-
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyDescription

---

---

EMAIL_TEMPLATE_COMPANY_INFO

Email-template-level company information (overrides COMPANY_INFO)

EMAIL_TEMPLATE_LOGO_INFO

Email-template-level logo (overrides LOGO_INFO)

EMAIL_TEMPLATE_BRAND_INFO

Email-template-level style/brand information (overrides BRAND_INFO). Accepts all 4 fields: textColor, tableBorderColor, tableHeadingBgColor, tableHeadingTextColor.

-
-

For example, to override the logo for a specific email template:

-
-
-
-
curl -v \
-     -X POST \
-     -u admin:password \
-     -H "X-Killbill-ApiKey: bob" \
-     -H "X-Killbill-ApiSecret: lazar" \
-     -H "Content-Type: application/json" \
-     -H 'X-Killbill-CreatedBy: admin' \
-     -d '{"logo":"data:image/png;base64,/9j/4AAQSk..."}' \
-     http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/EMAIL_TEMPLATE_LOGO_INFO
-
-
-
-
-

Default Templates

-
-

As mentioned earlier, the email notification plugin comes with some default templates.

-
-
-

For example, the default invoice creation template will result in the following email being sent:

-
-
-
-invoice email -
-
-
-

The default subscription cancellation template will result in the following email being sent:

-
-
-
-cancellation email -
-
-
-
-
-
-

Configuring the Plugin for Additional Events

-
-
-

As explained earlier, the email notification plugin is a notification plugin. In addition to the events handled by it by default, it can be configured to listen to other events and send emails accordingly.

-
-
-

In order to configure the plugin to send emails for other events, you will need to modify the plugin code as follows:

-
-
-
    -
  1. -

    Ensure that the event for which you would like to send an email is defined in the ExtBusEventType.java.

    -
    2. -
  2. -

    Modify the EmailNotificationListener class as follows:

    -
    -
      -
    1. -

      Modify the EmailNotificationListener#handleKillbillEvent method to add case statements corresponding to the events that need to be handled.

      -
      2. -
    2. -

      Add a method corresponding to the email that you would like to send similar to the EmailNotificationListener#sendEmailForUpComingInvoice method.

      -
      3. -
    -
    -
    3. -
  3. -

    Upload email templates and translation resource file corresponding to the email that you would like to send as explained in the "Managing Templates, Translations and Branding via API" section.

    -
    4. -
-
-
-
-
-

Customizing the Invoice Sent in an Email

-
-
-

Sometimes, you may need to customize the invoice sent in an email with additional fields. For this, you will need to create a custom plugin. The detailed instructions for this are mentioned in our Custom Email Invoice Formatter document.

-
-
-
-
-

Troubleshooting

-
-
-

This section covers some common issues and their solutions.

-
-
-

Emails not Sent

-
-

Sometimes, even after configuring the plugin as mentioned above, you may find that emails are not sent. There are several reasons for this:

-
-
-

Missing information on Account

-
-
-

In order to send an email, the Account record needs to have -the locale and email fields set. In addition, if you are using the default templates provided by the plugin, the company, address1, city, state, postalCode, country fields also need to be set on the Account. If any of these fields are missing, emails will not be sent and you will see the following exception in the Kill Bill logs:

-
-
-
-
com.samskivert.mustache.MustacheException: No key, method or field with name 'account.companyName'
-
-
-
-

Ensure that the account for which the emails are to be sent is configured with all the required fields as explained in the "Account Configuration" section above.

-
-
-

Missing information in template

-
-
-

Sometimes, you may upload a custom template. However, you may forget to upload the translation keys for it in the resource file. In such a case, the email will not be sent and you will see the following exception in the Kill Bill logs:

-
-
-
-
com.samskivert.mustache.MustacheException: No key, method or field with name 'text.merchantName'
-
-
-
-

Ensure that you also update the translation properties as specified in the "Uploading Resource Files" section above.

-
-
-
-

Enabling SSL in Emails

-
-

In order to enable SSL while sending emails, you need to configure the tenant with the org.killbill.mail.useSSL=true as specified in the "Tenant Config" section above.

-
-
-
-
-
- - - - \ No newline at end of file From 8c2e6d1fca459acc18e0394abd7c9284c09bafac Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:52:50 +0530 Subject: [PATCH 4/5] Fix code scan issues --- userguide/preview/aviate-revenue-recognition.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/userguide/preview/aviate-revenue-recognition.adoc b/userguide/preview/aviate-revenue-recognition.adoc index b196f48b3..d4fee46c2 100644 --- a/userguide/preview/aviate-revenue-recognition.adoc +++ b/userguide/preview/aviate-revenue-recognition.adoc @@ -92,7 +92,8 @@ A $500 one-time setup fee is recognized in full on its service start date. === Accounting Periods -An accounting period groups revenue entries by calendar month. Periods are identified by name, in the format `YYYY-MM` (for example `2026-04`). Every revenue entry belongs to the period named after the month of its date. For example, an entry dated `2026-04-17` belongs to period `2026-04`. +An accounting period groups revenue entries by calendar month. Thesystem 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*: @@ -222,7 +223,7 @@ Revenue belongs to the accounting period of its service date, not to the date th === Recognizing Revenue for a Specific Month -In production, revenue for a month is recognized by the regular runs as its days pass. All of a month's entries have been processed once a run has taken place on or after the last day of that month. +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: From a3dae3644f57c67eb1a453a3162077934b6c2542 Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Mon, 19 Oct 2026 18:11:07 +0530 Subject: [PATCH 5/5] Fix spacing in accounting periods description Corrected spacing in the accounting periods section. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- userguide/preview/aviate-revenue-recognition.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/userguide/preview/aviate-revenue-recognition.adoc b/userguide/preview/aviate-revenue-recognition.adoc index d4fee46c2..16135de6d 100644 --- a/userguide/preview/aviate-revenue-recognition.adoc +++ b/userguide/preview/aviate-revenue-recognition.adoc @@ -92,7 +92,7 @@ A $500 one-time setup fee is recognized in full on its service start date. === Accounting Periods -An accounting period groups revenue entries by calendar month. Thesystem 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`. +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*:
+
+
+
+

As the name implies, the email notification plugin is a plugin that sends out emails when certain events occur. This document covers how to install, test, and use this plugin, with support for both SMTP and AWS SES for sending email notifications.

+
+

Prerequisites

+
+
    +
  • +

    Ensure that you have Kill Bill, Kaui, and the database set up as explained in the Getting Started Guide.

    +
    • +
  • +

    Ensure that you have cURL installed. If you are on Windows, we recommend that you use Git Bash to run the cURL commands.

    +
    • +
  • +

    If you plan to use AWS SES, obtain your AWS SES credentials (access key and secret key) and ensure that the IAM user has the ses:SendEmail permission.

    +
    • +
+
+
+
+
+

Overview

+
+
+

The email notification plugin is a notification plugin. It listens to Kill Bill Events and sends emails accordingly.

+
+
+

Currently, the email notification plugin supports the following events:

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Event TypeEmail Description

INVOICE_CREATION

The customer will receive an email informing them that a new invoice is available.

INVOICE_NOTIFICATION

The customer will receive an email about upcoming invoices (The time at which to send the email can be configured through the org.killbill.invoice.dryRunNotificationSchedule property as specified in the Kill Bill Configuration Guide).

INVOICE_PAYMENT_SUCCESS

The customer will receive an email after each successful payment or refund.

INVOICE_PAYMENT_FAILED

The customer will receive an email after each failed payment.

SUBSCRIPTION_CANCEL

The customer will receive an email at the time a subscription was requested to be canceled and/or at the effective date of the subscription cancellation.

+
+

In addition, it can be extended to to handle other types of events as well. This is explained in the "Configuring the Plugin for Additional Events" section below.

+
+
+

To send an email the following is required:

+
+
+
    +
  • +

    The tenant or account must be configured to permit such event(s). This is explained in the "Plugin Configuration" section below.

    +
    • +
  • +

    The account for which the emails need to be sent must have certain fields set. This is explained in the "Account Configuration" section below.

    +
    • +
+
+
+
+
+

Plugin Installation

+
+
+

The email notification plugin can easily be installed via the Aviate UI. Refer to this doc for a detailed demo.

+
+
+

Alternatively, the plugin can also be installed either via Kaui or KPM as explained in the Plugin Installation Guide.

+
+
+

For example, to install the plugin via KPM, you can run the following command:

+
+
+
+
kpm install_java_plugin email-notifications --destination=<path_to_install_plugin>
+
+
+
+

If you would like to make changes to the plugin, you can clone the plugin code, build and deploy it as explained here.

+
+
+
+
+

Database Configuration

+
+
+

The email-notification-plugin requires some additional database tables. To create these tables, please follow the stes given below:

+
+
+
    +
  1. +

    Connect to the Kill Bill database.

    +
    2. +
  2. +

    Run the email-notification-plugin DDL.

    +
    3. +
+
+
+
+
+

Plugin Configuration

+
+
+

In order to use the email notification plugin, you need to configure either SMTP or AWS SES settings. Below are the steps to configure both:

+
+
+

AWS SES Configuration

+
+

To enable AWS SES for email notifications, add the following properties into killbill.properties. The default sender’s email must be verified in AWS SES.

+
+
+
+
org.killbill.email.notification.via.ses=true
+org.killbill.mail.from=<Default sender's email>
+org.killbill.aws.region=<AWS region, default region is us-east-1>
+
+
+
+

AWS SES requires authentication for sending emails. System-wide environment variables can be configured for all users by appending them to the /etc/environment file. Open the /etc/environment file in a text editor with root privileges, set the following variables:

+
+
+
+
AWS_ACCESS_KEY_ID=<AWS access key ID>
+AWS_SECRET_ACCESS_KEY=<AWS access secret>
+
+
+
+

Reboot the system to apply the changes.

+
+
+ + + + + +
+
Note
+		 +Note: Ensure that the credentials used have the necessary permissions, specifically ses:SendEmail, on the resource arn:aws:ses:<region>:<account>:identity/<sender’s email>. +
+
+
+
+

SMTP Configuration

+
+

A tenant needs to be configured with the SMTP properties required for sending emails. Additionally, the tenant can also be configured with the events for which emails should be sent. In addition to the per-tenant configuration, the plugin also allows a more granular account-level configuration for the set of emails to be sent for the particular account. Thus, either the tenant or the account needs to be configured with the events for which the email needs to be sent.

+
+
+

The configuration can easily be done via the Aviate UI Refer to this doc for a detailed demo.

+
+
+

Alternatively, the tenant configuration can also be done or via the Add a per-tenant configuration for a plugin endpoint as explained below:

+
+
+

Configure the tenant using the following cURL command (Replace <events> with a comma-separated list of the events for which the emails need to be sent. For example, to configure the tenant to send emails for INVOICE_CREATION and INVOICE_PAYMENT_SUCCESS, specify org.killbill.billing.plugin.email-notifications.defaultEvents=INVOICE_CREATION,INVOICE_PAYMENT_SUCCESS):

+
+
+
+
curl -v \
+     -X POST \
+     -u admin:password \
+     -H 'X-Killbill-ApiKey: bob' \
+     -H 'X-Killbill-ApiSecret: lazar' \
+     -H 'X-Killbill-CreatedBy: admin' \
+     -H 'Content-Type: text/plain' \
+     -d 'org.killbill.billing.plugin.email-notifications.defaultEvents=<events>
+org.killbill.billing.plugin.email-notifications.smtp.host=127.0.0.1
+org.killbill.billing.plugin.email-notifications.smtp.port=25
+org.killbill.billing.plugin.email-notifications.smtp.useAuthentication=true
+org.killbill.billing.plugin.email-notifications.smtp.userName=uuuuuu
+org.killbill.billing.plugin.email-notifications.smtp.password=zzzzzz
+org.killbill.billing.plugin.email-notifications.smtp.useSSL=false
+org.killbill.billing.plugin.email-notifications.smtp.sendHTMLEmail=true
+org.killbill.billing.plugin.email-notifications.smtp.defaultSender=xxx@yyy.com' \
+http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-email-notifications
+
+
+
+ + + + + +
+
Note
+		 +Note: On Windows systems, multiline cURL commands like the one above do not run property when cURL is used on the standard windows command prompt. So, we recommend using either Git Bash or Postman as explained here. +
+
+
+
+

SMTP Server Notes

+
+

In order to be able to use the email notification plugin to send emails, a local SMTP server is required.

+
+
+

We typically use the namshi/smtp docker image as follows to start a local SMTP server on port 25:

+
+
+
+
docker run -tid --name smtp_server -p 25:25  -e DISABLE_IPV6=true namshi/smtp
+
+
+
+

Alternatively, if you would like to use a non-docker based SMTP server, you can use MailSlurper. MailSlurper is a small handy SMTP server that can be useful for development and testing. It can be downloaded and configured as explained in its documentation.

+
+
+
+
+
+

Account Configuration

+
+
+

The account for which emails need to be sent, needs to have the email and locale fields set. In addition, the default email templates used by the notification plugin also require the company, address1, city, state, postalCode, country fields set on the Account.

+
+
+

Thus, ensure that the account is created using the following cURL command (Replace <email_id> with the email id where you would like to receive the email and change values for the other fields as required):

+
+
+
+
curl -v \
+    -X POST \
+    -u admin:password \
+    -H "X-Killbill-ApiKey: bob" \
+    -H "X-Killbill-ApiSecret: lazar" \
+    -H "Content-Type: application/json" \
+    -H "Accept: application/json" \
+    -H "X-Killbill-CreatedBy: demo" \
+    -H "X-Killbill-Reason: demo" \
+    -H "X-Killbill-Comment: demo" \
+    -d '{ "name": "John Doe", "email": "<email_id>", "currency": "USD", "company": "Acme Corporation", "locale":"en_US", "address1": "57 Academy Drive","city": "Oak Creek","state": "WI","postalCode": "53154", "country": "US"}' \
+"http://127.0.0.1:8080/1.0/kb/accounts"
+
+
+
+

Configure Events

+
+

Configure the account using the following cURL command (Replace {accountId} with the id of the account for which emails need to be sent and <events> with a comma-separated list of the events for which the emails need to be sent. For example, to configure the account to send emails for INVOICE_CREATION and INVOICE_PAYMENT_SUCCESS, specify "INVOICE_CREATION", "INVOICE_PAYMENT_SUCCESS"):

+
+
+
+
curl -v \
+     -X POST \
+     -u admin:password \
+     -H 'X-Killbill-ApiKey: bob' \
+     -H 'X-Killbill-ApiSecret: lazar' \
+     -H 'X-Killbill-CreatedBy: admin' \
+     -H 'Content-Type: application/json' \
+     -d '[<events>]' \
+    http://127.0.0.1:8080/plugins/killbill-email-notifications/v1/accounts/{accountId}
+
+
+
+

Note that either the tenant or the account should be configured with the events for which emails need to be sent, otherwise, emails will not be sent. Some scenarios for this:

+
+
+
    +
  1. +

    If a tenant is configured with some events, but the account is not configured, then emails will be sent based on what is configured at the tenant level.

    +
    2. +
  2. +

    If a tenant is not configured with any events but the account is configured with events, then emails will be sent based on what is configured at the account level.

    +
    3. +
  3. +

    If both tenant and account are configured with separate events, emails will be sent based on the events configured for both.

    +
    4. +
+
+
+
+
+
+

Testing the Plugin

+
+
+

Once the plugin is installed and configured as explained above, it can be used for sending emails. You can verify that the plugin is working correctly by following the steps given below:

+
+
+
    +
  1. +

    If you’re using SMTP, start a local SMTP server as explained in the "SMTP Server Notes" section. Otherwise, if you’re using AWS SES, make sure it’s configured as explained in the "Plugin Configuration" section.

    +
    2. +
  2. +

    Ensure that Kill Bill is running either in _standalone mode or in Tomcat.

    +
    3. +
  3. +

    Create a tenant as follows (specify the required apiKey and apiSecret):

    +
    +
    +
    curl -v \
+    -X POST \
+    -u admin:password \
+    -H "Content-Type: application/json" \
+    -H "Accept: application/json" \
+    -H "X-Killbill-CreatedBy: demo" \
+    -H "X-Killbill-Reason: demo" \
+    -H "X-Killbill-Comment: demo" \
+    -d '{ "apiKey": "bob", "apiSecret": "lazar"}' \
+    "http://127.0.0.1:8080/1.0/kb/tenants"
    +
    +
    +
    4. +
  4. +

    Create an account as follows (Replace <email_id> with the email id where you would like to receive the email and change values for the other fields as required):

    +
    +
    +
    curl -v \
+    -X POST \
+    -u admin:password \
+    -H "X-Killbill-ApiKey: bob" \
+    -H "X-Killbill-ApiSecret: lazar" \
+    -H "Content-Type: application/json" \
+    -H "Accept: application/json" \
+    -H "X-Killbill-CreatedBy: demo" \
+    -H "X-Killbill-Reason: demo" \
+    -H "X-Killbill-Comment: demo" \
+    -d '{ "name": "John Doe", "email": "<email_id>", "currency": "USD", "company": "Acme Corporation", "locale":"en_US", "address1": "57 Academy Drive","city": "Oak Creek","state": "WI","postalCode": "53154", "country": "US"}' \
+"http://127.0.0.1:8080/1.0/kb/accounts"
    +
    +
    +
    5. +
  5. +

    If successful, the command above returns a Location header like http://127.0.0.1:8080/1.0/kb/accounts/eda3e357-20a1-456d-a9b3-b39ca3db8020. Copy the account_id in the header (eda3e357-20a1-456d-a9b3-b39ca3db8020 in this case) and save it for future use.

    +
    6. +
  6. +

    If you’re using SMTP, configure the tenant as specified in the "Plugin Configuration" section above with INVOICE_CREATION and INVOICE_PAYMENT_SUCCESS events.

    +
    7. +
  7. +

    Add a payment method as follows (replace <account_id> with the account id obtained above):

    +
    +
    +
    curl -v \
+    -X POST \
+    -u admin:password \
+    -H "X-Killbill-ApiKey: bob" \
+    -H "X-Killbill-ApiSecret: lazar" \
+    -H "Content-Type: application/json" \
+    -H "Accept: application/json" \
+    -H "X-Killbill-CreatedBy: demo" \
+    -H "X-Killbill-Reason: demo" \
+    -H "X-Killbill-Comment: demo" \
+    -d '{ "accountId": "<account_id>", "pluginName": "__EXTERNAL_PAYMENT__"}' \
+    "http://127.0.0.1:8080/1.0/kb/accounts/<account_id>/paymentMethods"
    +
    +
    +
    8. +
  8. +

    If successful, the command above returns a Location header like +http://127.0.0.1:8080/1.0/kb/paymentMethods/c2ff0040-7c5b-48bf-9685-a4c57501535f. Copy the payment_method_id in the header (c2ff0040-7c5b-48bf-9685-a4c57501535f in this case) and save it for future use.

    +
    9. +
  9. +

    Set the payment method as default as follows (Replace <account_id> and <payment_method_id> with the values obtained above):

    +
    +
    +
    curl -v \
+    -X PUT \
+    -u admin:password \
+    -H "X-Killbill-ApiKey: bob" \
+    -H "X-Killbill-ApiSecret: lazar" \
+    -H "Content-Type: application/json" \
+    -H "Accept: application/json" \
+    -H "X-Killbill-CreatedBy: demo" \
+    -H "X-Killbill-Reason: demo" \
+    -H "X-Killbill-Comment: demo" \
+    "http://127.0.0.1:8080/1.0/kb/accounts/<account_id>/paymentMethods/<payment_method_id>/setDefault"
    +
    +
    +
    10. +
  10. +

    Create a external charge to trigger an invoice as follows (Replace <account_id> with the account_id obtained above):

    +
    +
    +
    curl -v \
+    -X POST \
+    -u admin:password \
+    -H "X-Killbill-ApiKey: bob" \
+    -H "X-Killbill-ApiSecret: lazar" \
+    -H "Content-Type: application/json" \
+    -H "Accept: application/json" \
+    -H "X-Killbill-CreatedBy: demo" \
+    -H "X-Killbill-Reason: demo" \
+    -H "X-Killbill-Comment: demo" \
+    -d '[ { "accountId": "<account_id>", "description": "My charge", "amount": 50, "currency": "USD" }]'    \
+    "http://127.0.0.1:8080/1.0/kb/invoices/charges/<account_id>?autoCommit=true"
    +
    +
    +
    11. +
  11. +

    Confirm that an email is sent for the invoice and successful payment.

    +
    12. +
+
+
+

Note that you can also use Kaui for executing steps 2-9 above.

+
+

Template and Resource Configuration

+
+

The email notification plugin uses Mustache templates for generating emails. This section explains how custom email templates can be configured.

+
+
+

There are three things you can customize for a given email:

+
+
+
    +
  • +

    A template: This constitutes the body of the email. It includes static text as well as variables which are replaced at runtime by the [mustache](https://mustache.github.io/) engine.

    +
    • +
  • +

    A resource file: This contains key-value pairs used to replace translation variables in a template, corresponding to a locale. See "Resources Overview" below.

    +
    • +
  • +

    Branding information: Company details, appearance/style, and logo, which can be set as a tenant-wide default (shared with invoice templates) and optionally overridden per email template type. See "Branding Overview" below.

    +
    • +
+
+
+

Templates Overview

+
+

An email template contains the body of an email. In addition to static text, it contains some variables which are replaced at runtime by the mustache engine.

+
+
+

The email notification plugin comes with some default templates. However, users can also upload their custom templates.

+
+
+

The email notification plugin uses one template per locale and per type (as opposed to one template per type with an additional set of translation string bundles for each locale). So, for example, the INVOICE_CREATION event can have templates like INVOICE_CREATION_en_US, INVOICE_CREATION_fr_FR, and so on. When an INVOICE CREATION email needs to be sent for a user, the user’s locale is checked and the corresponding template is used. The default templates are available only for the en_US locale, however, users can upload templates for other locales if required.

+
+
+
+

Resources Overview

+
+

In addition to templates, the email notification plugin requires a resource file. This resource file contains key-value pairs which can be used to replace variables in a template. The email notification plugin comes with a default resource file that contains key-value pairs for the variables in the default templates.

+
+
+

Unlike email templates, all the events have a single resource file. However, different locales can have different resource files. This allows having string translations in different languages, (like different translations for the catalog product names). So for example, you can have different resource files like Translation_en_US.properties, Translation_fr_FR.properties, and so on. When an email needs to be sent for a user, the user’s locale is checked and the corresponding resource file is used to replace the variables in the template.

+
+
+

The default resource file is available only for the en_US locale. Users can add additional key-value pairs to this resource file as well as add new resource files for different locales.

+
+
+
+

Branding Overview

+
+

In addition to the template and resource file, branding information — company details, appearance/style, and logo — can also be customized. This is read from the tenant_kvs table and can be set as a tenant-wide default shared across invoices and emails, and optionally overridden per email template type. See "Managing Templates, Translations & Branding via Aviate" and "Upload Branding Information" below.

+
+
+
+
+
+

Managing Templates, Translations & Branding via Aviate

+
+
+

While templates, translations, and branding information can all be uploaded directly via the Kill Bill API, Aviate — the premium UI/plugin layer on top of Kill Bill — is the recommended way to manage all three, since it provides a guided experience with a live email preview, inheritance indicators, and inline validation.

+
+
+ + + + + +
+
Note
+		 +Before you can configure templates, translations, or branding via Aviate, the Kill Bill instance must first be added as a deployment. See Aviate Deployment Management for details. +
+
+
+

Organization-level branding

+
+

Organization-level branding (company information and appearance) is shared between invoice and email templates, and is configured once. See Organization-level branding in the Invoice Templates document.

+
+
+
+

Email-template-level template and branding

+
+

Under Configuration → Email → Templates, configure a given email template (e.g. Invoice Creation) as follows:

+
+
+
    +
  1. +

    Select the desired template type from the drop-down (e.g. Invoice Creation).

    +
    2. +
  2. +

    Override company information and appearance for this template only, if required. Fields are pre-filled from the organization-level settings, with an indicator showing which are inherited versus overridden.

    +
    3. +
  3. +

    Customize style details such as text color, table heading background/text color, and table border color.

    +
    4. +
  4. +

    Use the live email preview panel to confirm your changes render as expected.

    +
    5. +
  5. +

    Click Save Template to save the changes.

    +
    6. +
  6. +

    Advanced users can also edit the underlying mustache template directly via Advanced View, instead of the structured fields in steps 2–3. This is not recommended unless you are familiar with the mustache template engine.

    +
    7. +
+
+
+

Repeat this for each email template type you want to customize.

+
+
+
+

Translations

+
+

Under Configuration → Email → Translation, configure translations as follows:

+
+
+
    +
  1. +

    Select the desired language from the drop-down.

    +
    2. +
  2. +

    Modify the translation strings, organized by category (e.g. Invoice, Payment).

    +
    3. +
  3. +

    Use the Preview drop-down to see how the translations render for a specific email template type.

    +
    4. +
  4. +

    Click Save Translation to save the changes.

    +
    5. +
+
+
+
+
+
+

Managing Templates, Translations & Branding via API

+
+
+

If you are not using Aviate, or need to script/automate these uploads, you can manage the template, resource file, and branding directly through the Kill Bill API, as described below.

+
+
+

Template/Translation Resource Keys

+
+

Each email template and the translation resource is assigned a key. To upload a custom email template/translation resource, its key needs to be specified.

+
+
+

The following table provides details about the template/translation resource keys (assuming that the locale is en_US):

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Template TypeTemplate KeyTemplate DescriptionDefault Template

Invoice creation

killbill-email-notifications:INVOICE_CREATION_en_US

Template for the email that will be sent when an invoice is created

InvoiceCreation.mustache

Upcoming invoices

killbill-email-notifications:UPCOMING_INVOICE_en_US

Template for the email that will be sent when an invoice is due

UpcomingInvoice.mustache

Successful payments

killbill-email-notifications:SUCCESSFUL_PAYMENT_en_US

Template for the email that will be sent when a payment is successful

SuccessfulPayment.mustache

Failed payments

killbill-email-notifications:FAILED_PAYMENT_en_US

Template for the email that will be sent when a payment fails

FailedPayment.mustache

Subscription cancellation (requested date)

killbill-email-notifications:SUBSCRIPTION_CANCELLATION_REQUESTED_en_US

Template for the email that will be sent when a user requests to cancel a subscription

SubscriptionCancellationRequested.mustache

Subscription cancellation (effective date)

killbill-email-notifications:SUBSCRIPTION_CANCELLATION_EFFECTIVE_en_US

Template for the email that will be sent when a subscription is actually cancelled

SubscriptionCancellationEffective.mustache

Payment refunds

killbill-email-notifications:PAYMENT_REFUND_en_US

Template for the email that will be sent when a payment is refunded

PaymentRefund.mustache

Translation strings

killbill-email-notifications:TEMPLATE_TRANSLATION_en_US

Includes all the text values referenced in the templates. Also includes the email subjects using the following keys: +upcomingInvoiceSubject +successfulPaymentSubject +failedPaymentSubject +paymentRefundSubject +subscriptionCancellationRequestedSubject +subscriptionCancellationEffectiveSubject +invoiceCreationSubject

Translation_en.properties

+
+
+

Uploading a Custom Template

+
+

As explained earlier, you can upload per-tenant email templates for various events. Let’s look at an example to upload a template for the next upcoming invoice for a locale en_US:

+
+
+
    +
  1. +

    Create the template /tmp/UpcomingInvoice.mustache:

    +
    +
    +
    *** You Have a New Invoice ***
+
+You have a new invoice from {{text.merchantName}}, due on {{invoice.targetDate}}.
+
+{{#invoice.invoiceItems}}
+{{startDate}} {{planName}} : {{invoice.formattedAmount}}
+{{/invoice.invoiceItems}}
+
+{{text.invoiceAmountTotal}}: {{invoice.formattedBalance}}
+
+{{text.billedTo}}:
+{{account.companyName}}
+{{account.name}}
+{{account.address1}}
+{{account.city}}, {{account.stateOrProvince}} {{account.postalCode}}
+{{account.country}}
+
+If you have any questions about your account, please reply to this email or contact {{text.merchantName}} Support at: {{text.merchantContactPhone}}
    +
    +
    +
    2. +
  2. +

    Upload the template for your tenant:

    +
    +
    +
    curl -v \
+-u admin:password \
+-H "X-Killbill-ApiKey: bob" \
+-H "X-Killbill-ApiSecret: lazar" \
+-H 'X-Killbill-CreatedBy: admin' \
+-H "Content-Type: text/plain" \
+-X POST \
+--data-binary @/tmp/UpcomingInvoice.mustache \
+http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/killbill-email-notifications:UPCOMING_INVOICE_en_US
    +
    +
    +
    3. +
  3. +

    If your template uses some additional keys than what are specified in the default translation file, these need to be added to the translation file as explained in the next section.

    +
    4. +
+
+
+
+

Uploading Resource Files

+
+

As explained earlier, you can upload additional resource files for different locales or additional keys in existing resource files. In order to do this, please follow the steps given below:

+
+
+
    +
  1. +

    Check if a resource file already exists for your locale. If so, download the file and if not, create a new file. You can use the default translation template as a reference to create a new file.

    +
    2. +
  2. +

    Add the required properties (key-value pairs) to your file.

    +
    3. +
  3. +

    Upload the new resource file using the following cURL command (Replace <template-name> with the name of the file created in the previous step and <translation_key> with the translation key. For example the translation key for a resource file for the en_US locale will be TEMPLATE_TRANSLATION_en_US):

    +
    +
    +
    curl -v \
+-u admin:password \
+-H "X-Killbill-ApiKey: bob" \
+-H "X-Killbill-ApiSecret: lazar" \
+-H 'X-Killbill-CreatedBy: admin' \
+-H "Content-Type: text/plain" \
+-X POST \
+--data-binary @/<template-name>.properties \
+http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/killbill-email-notifications:<translation_key>
    +
    +
    +
    4. +
+
+
+
+

Upload Branding Information

+
+

Branding fields (company info, style, logo) can be set directly using the [per-tenant user key/value endpoint](https://apidocs.killbill.io/tenant.html#add-a-per-tenant-user-key-value), the same mechanism used for invoice template branding.

+
+
+

Organization-level branding (COMPANY_INFO, LOGO_INFO, BRAND_INFO) is shared across invoices and emails — see ["Upload Branding Information"](https://docs.killbill.io/latest/invoice_templates.html#upload-branding-information) in the Invoice Templates document for those keys and example payloads.

+
+
+

To override branding for a specific email template type, use the corresponding EMAIL_TEMPLATE_* key instead:

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescription

---

---

EMAIL_TEMPLATE_COMPANY_INFO

Email-template-level company information (overrides COMPANY_INFO)

EMAIL_TEMPLATE_LOGO_INFO

Email-template-level logo (overrides LOGO_INFO)

EMAIL_TEMPLATE_BRAND_INFO

Email-template-level style/brand information (overrides BRAND_INFO). Accepts all 4 fields: textColor, tableBorderColor, tableHeadingBgColor, tableHeadingTextColor.

+
+

For example, to override the logo for a specific email template:

+
+
+
+
curl -v \
+     -X POST \
+     -u admin:password \
+     -H "X-Killbill-ApiKey: bob" \
+     -H "X-Killbill-ApiSecret: lazar" \
+     -H "Content-Type: application/json" \
+     -H 'X-Killbill-CreatedBy: admin' \
+     -d '{"logo":"data:image/png;base64,/9j/4AAQSk..."}' \
+     http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/EMAIL_TEMPLATE_LOGO_INFO
+
+
+
+
+

Default Templates

+
+

As mentioned earlier, the email notification plugin comes with some default templates.

+
+
+

For example, the default invoice creation template will result in the following email being sent:

+
+
+
+invoice email +
+
+
+

The default subscription cancellation template will result in the following email being sent:

+
+
+
+cancellation email +
+
+
+
+
+
+

Configuring the Plugin for Additional Events

+
+
+

As explained earlier, the email notification plugin is a notification plugin. In addition to the events handled by it by default, it can be configured to listen to other events and send emails accordingly.

+
+
+

In order to configure the plugin to send emails for other events, you will need to modify the plugin code as follows:

+
+
+
    +
  1. +

    Ensure that the event for which you would like to send an email is defined in the ExtBusEventType.java.

    +
    2. +
  2. +

    Modify the EmailNotificationListener class as follows:

    +
    +
      +
    1. +

      Modify the EmailNotificationListener#handleKillbillEvent method to add case statements corresponding to the events that need to be handled.

      +
      2. +
    2. +

      Add a method corresponding to the email that you would like to send similar to the EmailNotificationListener#sendEmailForUpComingInvoice method.

      +
      3. +
    +
    +
    3. +
  3. +

    Upload email templates and translation resource file corresponding to the email that you would like to send as explained in the "Managing Templates, Translations and Branding via API" section.

    +
    4. +
+
+
+
+
+

Customizing the Invoice Sent in an Email

+
+
+

Sometimes, you may need to customize the invoice sent in an email with additional fields. For this, you will need to create a custom plugin. The detailed instructions for this are mentioned in our Custom Email Invoice Formatter document.

+
+
+
+
+

Troubleshooting

+
+
+

This section covers some common issues and their solutions.

+
+
+

Emails not Sent

+
+

Sometimes, even after configuring the plugin as mentioned above, you may find that emails are not sent. There are several reasons for this:

+
+
+

Missing information on Account

+
+
+

In order to send an email, the Account record needs to have +the locale and email fields set. In addition, if you are using the default templates provided by the plugin, the company, address1, city, state, postalCode, country fields also need to be set on the Account. If any of these fields are missing, emails will not be sent and you will see the following exception in the Kill Bill logs:

+
+
+
+
com.samskivert.mustache.MustacheException: No key, method or field with name 'account.companyName'
+
+
+
+

Ensure that the account for which the emails are to be sent is configured with all the required fields as explained in the "Account Configuration" section above.

+
+
+

Missing information in template

+
+
+

Sometimes, you may upload a custom template. However, you may forget to upload the translation keys for it in the resource file. In such a case, the email will not be sent and you will see the following exception in the Kill Bill logs:

+
+
+
+
com.samskivert.mustache.MustacheException: No key, method or field with name 'text.merchantName'
+
+
+
+

Ensure that you also update the translation properties as specified in the "Uploading Resource Files" section above.

+
+
+
+

Enabling SSL in Emails

+
+

In order to enable SSL while sending emails, you need to configure the tenant with the org.killbill.mail.useSSL=true as specified in the "Tenant Config" section above.

+
+
+
+
+