Piano Revenue Recognition Report

About

Piano's revenue recognition report offers granular subscription data and advanced summarizations, making it a valuable tool for a client's finance and accounting departments. This report is based upon a subscriber's access, with revenue recognition starting from the start date of access for a given subscription.

Report Column Fields

The revenue recognition report includes the following fields:

Standard Transaction Type Fields

Here is a list and description of each transaction type within the Revenue Recognition report. Each row will in the spreadsheet will have a distinct transaction type:

• Cash in: This row indicates that a payment was received during the analysis period (the selected date range).

• Revenue recognition: This row shows the revenue recognition schedule in the event there is revenue recognized during the selected time range for a given transaction. In this row, the “Earned this period” column shows revenue recognized during the selected time period while the “Earned in Future” column shows deferred revenue.

• Cash out: Indicates that there was a refund for a given amount of money during the analysis period (the selected date range). Refunds can be full or partial.

• Revenue Adjustments: If there is a refund, either full or partial, this transaction type is used to adjust revenue recognition by the amount of the refund. Adjustments will appear as negative numbers.

Accrual Transaction Type Fields

In addition to the above standard transaction types, there is also the option to account for accrual revenue from subscriptions in grace (grace is a time period after payment failure where payment is re-attempted before a subscriber loses access).

If the parameter grace_period_enabled is set to true, the following transaction types will appear to account for grace-related events:

• Accrual cash in: This row indicates that an expected payment during the analysis period but that this payment didn’t occur yet because the subscription entered a grace period.

• Accrual revenue recognition: This row displays revenue recognition schedule for Accrual cash in. Even though payment has not yet been received in such an instance, this row will allow you to account for revenue based the renewal date rather than the transaction date.

• Accrual cash out: This transaction type is used when the grace period ends (either with payment or the subscription churning).

• Accrual revenue adjustments: This row cancels out “Grace Revenue Recognition” in the case a subscription is not successfully charged during grace.

If the transaction is successfully charged during grace, in the next reporting period there will be a "Cash in” line, a "Revenue recognition" line, and a “Accrual cash out” line to clear out the prior accrual revenue.

If the payment is not successfully charged during grace, there will be a “Accrual cash out” line and an “Accrual revenue adjustments” line to cancel out the previous “Accrual cash in” and “Accrual revenue recognition” lines. Note that these calculations are only relevant for subscriptions still in grace (if a subscription enters and exits grace in the analysis period it is recognized as any other subscription).

Note that if you set the grace_period_enabled parameter to false, the transaction types listed above will not appear in revenue recognition, but grace periods will still be accounted for. In such an instance, for a renewal successfully charged during grace, the revenue related to the grace access period will be added to the month the transaction is successfully charged.

Revenue Recognition API

The revenue recognition report's API documentation can be viewed here.

Here is the API endpoint that should be used: export/schedule/vx/revenue-recognition 

The API is similar to past versions of Piano's revenue recognition report, but there are new parameters that can be used. They are:

• separate_adjustments: The default is false. When this parameter is set to true, the report will separate revenues recognized previously up to the day of an adjustment (including refund and subscription exiting grace period without payment) and revenue to be recognized for both standard and accrual transaction types.

• gift_transactions: The default is true. When this parameter is set to false, gift subscriptions will not be included.

• grace_period_enabled: If this parameter is to false, accrual transaction types will not appear.

You can also use the "Get URL to download report export" API to produce link in order to download a CSV directly through the API.

Here is an example of a POST request for the report to appear in the Download Center:

curl --request POST \ --url 'https://reports-api.piano.io/rest/export/schedule/vx/revenue-recognition?api_token=XXXXX&aid=XXX&from=2024-02-01&to=2024-02-29&grace_periods_enabled=true&separate_adjustments=false&file_name=RevenueRecognitionReport_ClientName_2024_02'

When using the API call above, you will need to replace XXXXX with your API token and AID (as well as date range and desired filename). After running this API call, you will get a response saying this report is being created with an export_id, and the report will appear in the Download Center.

You will need the export_id above if you prefer receiving revenue recognition reports using URL. Here's is an example of a GET request which will generate a link to download the report in the CSV format:

curl --request GET \ --url 'https://reports-api.piano.io/rest/export/download/url?api_token=XXXXX&aid=XXXXX&export_id=XXXXX'

Revenue Recognition FAQs

How does the revenue recognition report’s grace period logic work?

When there’s a payment failure for a subscription renewal, most Piano clients include a grace period for a limited timeframe, within which the subscriber maintains access and payment will be reattempted before the subscriber loses access. The revenue recognition report accounts for this grace period.

Since not all Piano clients want to deal with the complexity of accrual accounting, the revenue recognition report gives you the option to show only successful transactions. If you set grace_period_enabled as false, the grace access period will still be reflected in the revenue recognition schedule when a subscription ultimately has a successful payment.

If you chose to show subscriptions in grace, you will see these subscriptions represented by the accrual transaction types noted above. In such a case, if the payment goes through in a future reporting period, there will be three lines in the report, Cash in (to account for the payment), Revenue Recognition (to recognize the revenue of the payment), and Accrual cash out (to account for the end of accrual).

On the other hand, if payment fails after grace period ends, then there will be Accrual cash out and Accrual revenue adjustments lines to account for the churned subscriber.

The first tab in this sheet shows examples of what such grace periods would look like in each month under different scenarios. There is an example for both a successful payment after grace period ends and a payment failure after grace period ends.

Note that the “External Tx Id” field is only populated once an actual transaction takes place. That’s why those columns are empty in grace lines in January for both examples and for both January and February for the example where payment is unsuccessful in grace.

In this month’s version of the revenue recognition report the values for prior months are different. Why is this?

One important detail to understand is that a given time period's report only reflects the past, current, and future revenue of subscriptions that had revenue recognized in that time period. That means, if a subscription ended or was refunded in the month prior, it will not show up on this month’s version of the report.

When looking at the current month, you will still see revenue for past months. However, that past revenue is only related to subscriptions that have revenue recognized in the current time period.

For example, let's say that in February you had five subscriptions which have $10 recognized in the month. However, one of those subscriptions is ending in the middle of the month (auto-renew is disabled on the subscription so renewal will not be attempted). That means that subscription is only worth $5 for February. The total recognized revenue for the five subscriptions in February is therefore $45 ($10*4 + $5*1).

If you look in March at February revenue, you will not see the $5 subscription any longer because it has no revenue recognized in the current analysis period. So you would just see $40 in February revenue when looking at the March report. This means that, if you are closing the books on a particular month, you should always use that month’s version of the revenue recognition report to close that month.

There are three reasons that, when looking at the current month, revenue recognition changes for past months. The first reason, as illustrated above, is because of subscriptions which expire, either because they were canceled or because they did not have auto-renewal enabled. In these cases, once the subscription ends, reports generated for periods after this expiration will not reflect the prior value for this subscription since it no longer exists in the present period.

The second reason is refunds. If there was a full refund in July and that subscription therefore has no revenue implications moving forward, that transaction would not be present in the August report or other future reports.

The third reason that revenue can be different is related the grace period logic (only relevant if you have chosen to show subscriptions currently in grace). For a user who had a payment failure in July, was in grace throughout all of July, and then was successfully charged during grace in August, the July revenue would be recognized under “accrual revenue recognition” in the July version of the report and under standard “revenue recognition” in the August version of the report.

Note that the values for “accrual revenue recognition” and “revenue recognition” would be exactly equivalent in such a grace scenario since you would never want to have to re-open your books for closed months. That means, if you had recognized $5 as “accrual revenue recognition” in the July version of the report, and the payment was successfully charged in August, you’d then have $5 categorized as “revenue recognition” for July in the August version of the report.

How are refunds handled in revenue recognition reporting?

Piano support both full and partial refunds. How these refunds appear within revenue recognition depends on the type of refund and whether the refund requires an adjustment for previously recognized revenue. The second tab in this sheet shows examples of various kinds of refunds.

One of the most common partial refunds is when a Piano client refunds revenue for future subscription periods but not for past periods already consumed. When this happens, past revenue recognition will not change and a “Cash out” row will appear for the refunded amount along with a “Revenue recognition” row to reflect the adjustment for the current and future reporting periods. This “Revenue adjustment” will not adjust values for past months since that past revenue has not been refunded but only future revenue.

Within Piano you can also do partial refunds that do not refund all deferred revenue. The revenue recognition report will adjust in these circumstances. For example, say an annual subscription starts on January 1st and is refunded on April 16th, but you do a partial refund accounting for revenue through the end of April. Imagine that left over April 16th-April 30th revenue is worth $2.50.

The earned revenues will stay unchanged between January 1st and April 15th. However, the revenue earned on April 16th-30th will be attributed evenly to dates between April 16th and December 31st, the remaining access period of the original subscription term.

This revenue will be divided as evenly as possible across the remaining subscription period. Please check answer below for “What happens if revenue cannot be equally divided between the days of the subscription?” for additional explanation on this point.

When it comes to refunds, the revenue recognition only accounts for refunds date and refund amount without considering refund reason. If this refund is not for cancellation but for reasons like discount or downgrade, the record would be same as above. A “Cash out” record will appear for the refunded amount along with “Revenue recognition” with adjusted values.

If it is a full refund that happens in the same month as the date of the original transaction, there will only be “Cash in” and “Cash out.” Revenue recognition will not be shown in the report, unless separate_adjustments is set to true.

Also, with the separate_adjustments parameter set to true you can account for all revenue that was recognized up to the date of an adjustment (even if all that previously recognized revenue was refunded). When this parameter is set to true, there will be a “Recognized revenue recognition” row that will differentiate all revenue recognized prior to the adjustment and revenue that was to be recognized after the adjustment (deferred revenue).

For clients who instead want to perform such calculations by month, even with the separate_adjustments parameter set to false, if a full refund happens in different months and revenue has already been recognized in previous months, a "Revenue adjustments” row will be produced in the month that the refund occurred.

This record will have a negative value in the current month for revenue recognized in the previous months and the current month. For revenue to be adjusted for future months (for deferred revenue), this record will show opposite numbers from revenue recognition for months through the access end date.

How are bundled subscriptions represented in the revenue recognition report?

Bundled subscriptions will be identified by term name and resource name in the revenue recognition report as a single line item. You can create a specific term name or resource name for the bundle to understand that the revenue associated with that subscription is for the bundle. A single term can include a bundled resource.

If an existing subscriber upgrades to a higher-priced subscription, how and when does the revenue recognition report start to recognize revenue for the upgraded subscription?

The answer depends on whether you configure the upgrade to charge the user for the higher-priced subscription immediately or upon renewal.

If a user upgrades to a higher priced subscription, and you have set upgrades to bill immediately, then the user will be billed the prorated incremental value immediately. The upgrade will not affect the original revenue recognition record, meaning the record of the original subscription ID will stay the same in the revenue recognition report. Instead, a record for “Cash in” will be created for the price difference the user paid under a new subscription ID, and a “Revenue recognition” record will be created and attribute those revenues between payment date and access end date

This means there will be two subscription IDs co-existing in the report from the upgrade date until the end of the original term. On the renewal date, a new record will be created in the report for this renewal transaction, which will look like a regular renewal under the new subscription ID.

The other option for upgrades is to charge for the upgrade upon renewal. If this user upgrades to a higher-priced subscription without paying, no change will be made to the revenue recognition report and only the record from the original subscription will appear in the report until the user renews. Then, upon renewal, the user will be charged at the price of the higher-tier subscription and the standard subscription will no longer appear in revenue recognition reporting.

The third tab in this sheet shows examples of how both upgrades and downgrades appear in the report.

What happens in revenue recognition if a subscriber downgrades from a higher-priced subscription to a lower-priced subscription?

A downgrade is shown as a partial refund in the revenue recognition report. The report would not show the new subscription ID until the renewal. Please see the question “How are refunds handled in revenue recognition reporting?” for additional context. The third tab in this sheet shows examples of how both upgrades and downgrades appear in the report.

What happens if revenue cannot be equally divided between the days of the subscription?

Because it is unlikely that the subscription price will be an exact multiple of the number of days of access, the nearest exact multiple lower than the price is used to determine base revenue recognized per day. Any remaining revenue is then divided equally per day over the end of the subscription.

For example, if a 365 day subscription costs $100, then each day of the subscription is worth approximately $0.274. Because you can not distribute a fraction of a penny, the revenue recognition report rounds the revenue down to the nearest penny, with each day having a base worth of $0.27 in this instance.

The remaining funds ($1.45) are spread out as evenly as possible across the access period (i.e. in this example $0.01 might be recognized every other day to distribute revenue as evenly as possible). Looking by month, for this example, the report would show $0.11 in February, $0.13 for two of the 31-day months, and $0.12 for the remaining months.

Is Piano informed when a chargeback happens? How can one zero out these subscriptions from revenue recognition?

Chargebacks happen when a subscriber contacts their bank and disputes the transaction. These are not the same as refunds, which Piano accounts for automatically in revenue recognition. When a chargeback occurs, the payment processor gets informed of this event, but Piano does not.

To rectify this, you will need to identify such chargebacks within your payment processor and then cancel those subscriptions within Piano (cancellation without giving a refund is possible within Piano). You will then need to identify the associated transaction within the revenue recognition report and cancel out any recognized revenue manually.

What happens in revenue recognition if the subscription end date is extended or shortened without payment? For example, what if an existing subscriber’s subscription is extended for a month as a gesture of good will?

Piano’s revenue recognition report only alters records for transactions with associated access adjustments, so access extension without payment/refund will not be reflected in the revenue recognition schedule. The same is true for free trials. Piano does not begin to recognize revenue unless a payment occurs, with the exception of grace, where access has been provided in relation to an expected payment.

Can Piano recognize revenue from subscriptions that occur in third-party systems?

No, Piano only does revenue recognition reporting for payments transacted through Piano. This report therefore will only contain information about transactions processed via Piano. In case you have any imported legacy subscribers, their transaction data will not be available in this report. Any transactions will be recognized only after their subscriptions are renewed in Piano directly. The data about the legacy transactions should be available in the 3rd party system that was used to bill them in the past.

What is the time zone of the revenue recognition report?

The timezone of the report is set to UTC.

Are taxes included in revenue recognition?

Taxes are excluded from this revenue recognition by default. Taxes collected are visible in “Tax rate” and “Paid this Period (tax)” columns, but they do not factor into revenue recognition calculations since tax liability cannot be deferred.

Note that Piano cannot include VAT in revenue recognition given that VAT occurs outside of Piano and therefore is not stored in Piano's databases.

How are gifts handled in revenue recognition?

For gift subscriptions, the record for “Cash in” and “Revenue recognition” will appear once the transaction is complete.

Prior to the gift being redeemed by the recipient, revenue for that gift subscription will be recognized at the end of the redemption period, which is one year from the payment date.

Once the gift is redeemed by the recipient, revenue recognition is altered, and the revenue will be attributed between access start date (the redemption date) and the access end date. In the event a gift subscription is not redeemed within that year, the report will recognize the whole transaction amount at the end of the redemption period when the gift expires.

In the fourth tab of this sheet are examples of gift subscriptions redeemed at the same month of transaction, after a number of months, and never redeemed.

Why does the transaction revenue recognition report generated via the API differ from the one automatically generated each month in the Download Center?

The transaction revenue recognition report can differ slightly depending on whether it's generated via the API or downloaded from the Download Center because the two methods rely on different versions of the revenue recognition logic. The Download Center report is generated using the older version of the revenue recognition calculation, while the API returns results based on the latest version.

As a result, you may notice minor discrepancies in how values are distributed across individual days or transactions. These differences come primarily from how access days are counted (365 vs. 366 days) and how intermediate values are rounded. At the line-item level, the variance is typically only a few cents, but those cents can accumulate into larger apparent differences when viewed on a monthly aggregation.

It's worth noting that, when totals are summed at the monthly level, both versions reconcile to the same final amount. No revenue is lost or duplicated between the two methods, only the day-by-day distribution varies.

Last updated: June 23, 2026