Revenue Recognition - Alguna Docs

Revenue recognition turns what you billed into what you earned, period by period, in line with ASC 606 and IFRS 15: revenue is recognised as the service is delivered, not when the invoice goes out or the cash arrives. In Alguna this is not a separate module you feed data into. The same subscription that produced the invoice produces the revenue schedule — deferred revenue when the invoice is issued, recognised revenue as each period passes, contract asset when service has been delivered but not yet billed — and the schedule is readable per subscription, per customer, per legal entity, or for the whole organization. Use this page to understand how the numbers are produced and to pull them through the API. This is the last link in the chain described in How Alguna Works: catalog → subscription → invoice → payment and revenue. Collections and payments do not change recognised revenue; see Collections.

From subscription to schedule

Moment	Effect on the schedule
Invoice issued in advance of service	The billed amount is deferred and released over the service period the lines cover
Service delivered before it is billed (arrears, usage)	Revenue is recognised as delivered and carried as a contract asset until the invoice is issued
Each period passes	A slice of deferred revenue moves to recognised, according to the product’s allocation method
Payment received	No effect on revenue; cash replaces the receivable
Credit note applied	Reduces the revenue of the periods it credits

Each product’s fee_type and payment_terms (advance or arrears) decide which path a line takes; its revenue_allocation_method decides how the amount spreads across periods.

Multi-year contracts

A three-year deal that escalates —

1,200, then

1,320, then

1,452 — is billed a year at a time, but the customer gets the same service in every month of it. With a legal entity's **revenue allocation mode** set to `total_contract` and period close enabled for your organisation, the whole

3,972 is earned evenly across the 36 months instead of stepping up each year. On per_period, the default, each year is earned over that year, as before. Set it as Revenue allocation on the Legal entities settings page: Per billing period or Total contract. A single contract can differ from its legal entity: on the subscription’s Revenue Schedule tab, Revenue allocation is Use legal entity default, Per billing period or Total contract. Changing it needs the Manage Revenue Schedules permission, which admins have and sales roles do not. Use it for a fixed-term contract with free months at the start. A 12-month contract whose first two months are free and whose other ten bill

120 earns

100 in every month under Total contract. The free months build a contract asset that each invoice then draws down. Both settings appear once period close is enabled for your organisation, and neither is in the public API. The Legal entities page is not in the settings menu. Open it directly: Production or Sandbox. A change to either setting that would move a month you have already closed is refused unless the difference is booked into the open month instead.

When a charge is earned

Alguna works out when each charge is earned from how its price is billed: a one-off charge on the day it is delivered, everything else evenly across the period it covers. Some products transfer control the other way — a perpetual licence billed quarterly is earned when it is handed over, an onboarding fee delivered across the term is earned across it. Set the product’s recognition method to point_in_time or over_time and, once period close is enabled for your organisation, the schedule follows it instead. Leave it unset and the existing inference stands.

Prepaid credits

Credits bought in bulk are earned as the customer draws them, not evenly across the period they were billed for: a month that draws a fifth of the balance earns a fifth of what was paid for it. Once period close is enabled for your organisation, Alguna reads the draw-downs recorded against each prepaid price and recognises the balance in that proportion. While the term is still running, credits the customer has not drawn stay deferred — they may yet use them. Once it is over, whatever is left is breakage you are entitled to, recognised when the balance expires:

1,000 of credits drawn 3,000 then 5,000 against a 10,000 balance earns

300 and

500, and the remaining

200 when the term ends. If your history lets you estimate breakage up front, ask support to turn on estimated breakage. The unused credits are then earned in proportion to the credits the customer did draw, so the same balance earns

375 and

625. Because that spreads breakage back over months already reported, a month you have closed is caught up in your open month rather than restated.

Non-distinct fees

A one-off charge — a setup or implementation fee — is normally recognised on the day it is delivered. Some of them transfer nothing to the customer on their own: they are an advance payment for the service the contract goes on to deliver. Mark the product non-distinct and, once period close is enabled for your organisation, its fee is earned evenly over the contract term instead. A

600 setup fee on a

1,200 annual subscription then recognises

150 a month for twelve months rather than

700 in the first month and $100 thereafter. The contract needs an end date for the fee to be earned over.

Allocation methods

The method is set per product, so one contract can mix methods across its lines. Set it through revenue_allocation_method on POST / PATCH /products/{id} or on the product page under Revenue Recognition. See Create a product.

`revenue_allocation_method`	Behaviour	Use for
`straight_line`	Equal allocation per period within each billing cycle. The default.	Most subscription revenue
`usage_based`	Allocated in proportion to metered usage in each period	Consumption revenue, under the variable-consideration guidance
`contract_level_straight_line`	Total contract value spread evenly across the whole contract, ignoring per-period price differences	Ramped pricing, free months, and annual escalators, where per-period pricing does not reflect delivery

curl -X PATCH https://api.alguna.io/products/prod_abc123 \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{ "revenue_allocation_method": "contract_level_straight_line" }'

import os

import requests

response = requests.patch(
    "https://api.alguna.io/products/prod_abc123",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={"revenue_allocation_method": "contract_level_straight_line"},
    timeout=10,
)
response.raise_for_status()
print(response.json()["revenue_allocation_method"])

Straight-line example

A $1,200 annual subscription billed in advance on January 1:

Month	Recognised	Cumulative	Remaining deferred
January	$100	$100	$1,100
February	$100	$200	$1,000
…	…	…	…
December	$100	$1,200	$0

Usage-based example

A metered product billed in arrears at $0.01 per call:

Month	Usage	Recognised	Contract asset until invoiced
January	10,000	$100	$100 until the January invoice issues
February	15,000	$150	$150 until the February invoice issues

Read revenue schedules

Four endpoints return the same shape at different scopes. Each takes currency (the currency to report in) and interval (daily or monthly). See Revenue Schedules.

Endpoint	Scope
`GET /revenue-schedules`	Whole organization
`GET /revenue-schedules/legal-entity/{id}`	One legal entity
`GET /revenue-schedules/customer/{id}`	One customer
`GET /revenue-schedules/subscription/{id}`	One subscription

curl "https://api.alguna.io/revenue-schedules/subscription/sub_abc123?currency=USD&interval=monthly" \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

response = requests.get(
    "https://api.alguna.io/revenue-schedules/subscription/sub_abc123",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
    },
    params={"currency": "USD", "interval": "monthly"},
    timeout=10,
)
response.raise_for_status()

schedule = response.json()
for entry in schedule["entries"]:
    print(
        entry["start_date"],
        "recognised", entry["new_recognized_revenue"],
        "deferred balance", entry["total_deferred_revenue"],
        "contract asset", entry["total_contract_asset"],
    )

const schedule = await alguna.revenueSchedules.getBySubscription("sub_abc123", {
  currency: "USD",
  interval: "monthly",
});

The response is currency, start_date, end_date, interval, and chronologically ordered entries. Each entry has a new_* figure (the change in that period) and a total_* figure (the cumulative balance) for:

Series	Meaning
`recognized_revenue`	Revenue earned — the sum of fixed and metered
`fixed_revenue`	Recognised revenue from fixed-price lines
`metered_revenue`	Recognised revenue from usage lines
`one_off_revenue`	The portion of the above from one-off (non-recurring) charges
`deferred_revenue`	Billed but not yet earned
`contract_asset`	Earned but not yet billed

new_deferred_revenue is negative in periods where more is released than billed. The organization and legal-entity schedules convert every subscription into the requested currency using the FX rates you maintain — see Multi-currency below.

MRR, ARR, and ACV

Recurring-revenue metrics are separate from the schedule and are available per subscription:

curl https://api.alguna.io/subscriptions/sub_abc123/revenue \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

response = requests.get(
    "https://api.alguna.io/subscriptions/sub_abc123/revenue",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
    },
    timeout=10,
)
response.raise_for_status()

metrics = response.json()
print(metrics["mrr"], metrics["arr"], metrics["acv"], metrics["recurring_revenue_status"])

const metrics = await alguna.subscriptions.getRevenue("sub_abc123");

recurring_revenue_status is complete, partial, or unavailable — whether MRR and ARR include all matrix-priced recurring revenue. The same numbers are available for a specific version at GET /subscriptions/{id}/versions/{vid}/revenue and through GET /insights/revenue/subscription/{id}. Organization-wide net revenue, and revenue broken down by customer, product, and movement (new, expansion, contraction, churn), are on the Insights endpoints.

Handling changes

Because subscriptions are versioned, every change that affects revenue is a published version with an effective date, and the schedule is regenerated from it:

Upgrade or added product mid-term — the new version’s lines produce their own deferred and recognised amounts from the effective date; proration shows up as its own invoice lines and is recognised over the remaining period.
Upgrade as a separate contract — a product set to the separate_contract revenue modification treatment, added part-way through a term, is recognised as a contract of its own: its amount spreads over the term from the change rather than over the term it was added to. This only applies once period close is enabled for your organisation; otherwise the addition is folded into the contract it amends.
Downgrade or removal — remaining deferred revenue for the removed lines is released or reversed according to what was credited. Once period close is enabled, a product set to the cumulative_catch_up treatment is re-measured instead: the revised contract value is spread evenly over the whole term and the difference against what has already been recognised books in the month of the change, so that month can carry a negative amount. Without the treatment the change is recognised prospectively — what was recognised stands, and the rest is spread over the remaining term.
Cancellation — recognition stops at the cancellation date. Any refund is a credit note and reduces revenue in the credited periods.
Credit notes — reduce recognised revenue for the periods the credited lines cover. Once period close is enabled for your organisation, the original revenue stands and the credit is reported instead as a reversal in the month the credit note is dated.
Annual committed spend — once period close is enabled, a metered price with an annual minimum spend earns an equal share of that commitment every month; usage below the share is recognised against a contract asset, which is released as later usage catches up, so the year recognises the commitment or the usage, whichever is larger.

Preview the financial effect of a change before committing it with POST /subscriptions/{id}/changes/preview. See Subscription Changes.

Closed periods

A month that has been reported on should not move. Closing an accounting period for a legal entity — from the Revenue Recognition page — seals that month: Alguna stores a snapshot of each subscription’s revenue schedule as it stood at the close, plus one for the entity’s ad-hoc invoice revenue. Every later report — for a subscription, a customer, the legal entity or the whole organization — reads the closed month from those snapshots rather than recomputing it. A restated invoice, a late credit note or a corrected price therefore leaves the closed month’s recognised, deferred and contract-asset figures exactly as they were reported. The change is not lost. The difference between what the closed month reported and what today’s inputs produce is booked as a catch-up adjustment in the open month, which is where a correction belongs once a period is closed. Reopen the period if the month genuinely has to be restated, then close it again to reseal it. Months that are not closed are still computed from live data on every request, so they always reflect the current state of the subscription. A snapshot is taken with the legal entity’s own recognition settings, so a report asked for on a different amortization basis, or with a revenue category excluded, is computed live throughout. A customer-scoped report covers only part of a legal entity’s ad-hoc invoices, so its ad-hoc revenue is also computed live. If you have already been closing months outside Alguna, ask your account team to seal that history for you first, so you start closing from the month after the last one you closed by hand.

Multi-currency

Schedules are produced in the currency each subscription bills in. When you ask for a schedule in another currency, or for a legal entity or the organization, amounts are converted with the FX rates you maintain under Settings → Workflows → Billing → FX Rates — each rate has a validity period, so historical periods keep the rate that applied at the time. See Multi-Currency.

	EUR	USD at 1.10
Invoice amount	€1,000	$1,100
Monthly recognition	€83.33	$91.67

Which date’s rate applies depends on how the revenue is billed. By default a fixed-term subscription’s fees convert at its contract start date, and usage and rolling subscriptions at the start of each charge period. Once period close is enabled for your organisation, revenue converts at the date of its transaction instead, which is how your ledger books the invoices:

Billed in advance — at the date of the invoice that billed it, in every month it is recognised in. A two-year contract invoiced annually converts each year at its own invoice’s rate. A period not yet invoiced converts at its start until the invoice is issued.
Billed in arrears, and usage — at the rate of the month it is recognised in. With reference rates, the legal entity’s treatment (daily, month end or month average) picks the rate within that month.
Credit notes — at the rate of the invoice they credit, so a fully credited invoice leaves no deferred revenue behind in the reporting currency.

Months you have already closed keep the rates they were reported at. Conversion never falls back to an assumed rate. If a schedule or report needs a rate that is not defined for the period — a subscription billing in a currency you have no rate for, or a rate whose validity period does not cover the dates concerned — the request fails with 412 Precondition Failed and the error message lists each missing pair: the legal entity, the source and target currencies, and a date the rate was needed for. This applies to the schedule endpoints above, to the RPO report, and to CSV exports from the dashboard. Add the rate under Settings → Workflows → Billing → FX Rates and request the report again. Lines whose amounts are all zero need no rate.

Accounting integrations

With an accounting integration connected, Alguna posts the journal entries that the schedule implies — deferred revenue on issue, recognition each period — to the connected ledger, so you do not re-key them at close. See QuickBooks, Xero, and NetSuite. Each journal entry carries a snapshot of the legal entity’s revenue schedule in the entity’s currency. If that conversion needs an FX rate that is not defined, the entry is not created and the error names the missing pair, the same way a report does; add the rate and post again. Journal entries are posted per legal entity, per month, from the Revenue Recognition page. Each entry has an entryType: standard, the month’s primary entry, or adjustment, a correction posted on top of a month that already has one. A legal entity can have at most one standard entry per month, where the month is that of the entry date in UTC; a second standard entry for the same month is rejected. To correct a month that has already been posted, post an adjustment entry for the difference rather than re-posting the month — the ledger sums the entries for that month, so the adjustment carries only the change. The dashboard classifies an entry automatically: the first entry posted for a month is standard, and when the month already has a standard entry the dialog says so and posts the new entry as an adjustment. Two legal-entity settings decide which revenue appears in the schedule stored with each journal entry (and attached to it in Xero). Both default to true; the line amounts you post are what you enter.

Setting	When `true`
`excludeMonthlyRevenueFromPosting`	Leaves out lines whose billing period is a month or less. Those invoices already reach the ledger as revenue through the invoice sync, so carrying them in the journal entry would recognise them twice.
`excludeMeteredRevenueFromPosting`	Leaves out the usage portion of metered prices billed in arrears. A prepaid fixed portion of the same price stays in.

Set a setting to false to include that revenue. Alguna manages these settings for you: they are not on the legal-entity form in the dashboard or in the public API, so ask support to change them for a legal entity. For your own reconciliation the schedule endpoints above are the source of truth; pull them at month end and tie total_deferred_revenue to the deferred revenue account.

Closing a period and the audit trail

Closing a month seals it: Alguna stores the recognition each subscription had at that moment, and journal entries dated inside a closed month are rejected until it is reopened. A closed month’s reported figures never change afterwards. When something upstream moves — an invoice voided, a credit note issued, a subscription corrected — the difference is booked as a catch-up adjustment in the open month rather than restating the month you have already reported. Each adjustment records why it exists and what it came from: the reason, the invoice, invoice line or credit note behind it, and the stored recognition it was measured against. Correcting the same month twice does not double count — the second correction nets against what was already booked. Once a month is closed, Alguna drafts its journal entry for you from the recognition it sealed, at the level of detail your legal entity is configured for. A draft is never sent to your accounting system on its own: you review it and post it, exactly as you would an entry you had entered yourself. The month’s revenue summary can also be exported as a CSV from the Revenue Recognition page — the same figures the journal entry is drafted from, so the export and the entry always agree, and a closed month’s export is identical every time you take it. Alongside this, each legal entity has an audit trail of everything that shaped its books: periods closed and reopened (with who and when), the recognition captured at each close, the journal entries posted, and the catch-up adjustments booked. Every row carries its timestamp, the entity it concerns, the user or process responsible, and the details of the change, so an adjustment can be traced back to its cause without re-deriving anything.

In the dashboard

Revenue Recognition shows recognised and deferred revenue by period, with drill-down by customer and product; each subscription also has a Revenue Schedule tab. Each month carries its status — open, or closed with who sealed it and when — with Close period, Reopen, Export, and the month’s journal entry alongside it, the adjustments booked into a month expand under the table, and an Audit Log tab shows the legal entity’s whole trail. Revenue Insights covers net revenue, movement, and top customers — see Insights.

Data quality

Two conditions distort the schedule without stopping it from being produced. An active or cancelled subscription with no billing schedule contributes nothing, because the schedule is derived from what the subscription bills, so its revenue is missing from every schedule and report. A billing schedule entry whose invoice no longer exists — deleted after issue, or a historical import that referenced an invoice that was never there — is still scheduled from its billing entry, but without the invoice the schedule cannot see whether the invoice was voided or cancelled or how much of it was credited, so that entry’s revenue can be overstated. Neither condition is flagged in the figures themselves. If a subscription looks under- or over-recognised, open it in the dashboard and check that it is on the plan and items you expect; cancel it if it should not be billing at all. Alguna support can run a check for both conditions across your organization on request and repair a broken invoice reference, so ask before closing a period if you suspect either is hiding in the month’s figures.

Next steps

Insights

Net revenue, billings, A/R ageing, and customer metrics.

Multi-Currency

FX rates and reporting currency.

Revenue Assurance

Find usage that should have been billed.

Accounting integrations

Post entries to your ledger.

​From subscription to schedule

​Multi-year contracts

​When a charge is earned

​Prepaid credits

​Non-distinct fees

​Allocation methods

​Straight-line example

​Usage-based example

​Read revenue schedules

​MRR, ARR, and ACV

​Handling changes

​Closed periods

​Multi-currency

​Accounting integrations

​Closing a period and the audit trail

​In the dashboard

​Data quality

​Next steps

Insights

Multi-Currency

Revenue Assurance

Accounting integrations

From subscription to schedule

Multi-year contracts

When a charge is earned

Prepaid credits

Non-distinct fees

Allocation methods

Straight-line example

Usage-based example

Read revenue schedules

MRR, ARR, and ACV

Handling changes

Closed periods

Multi-currency

Accounting integrations

Closing a period and the audit trail

In the dashboard

Data quality

Next steps