FAQ - Subscription Insights | Piano Help Center

What is Subscription Insights?

Subscription Insights is an analytical product that streams events from Composer, Subs billing , and ID to the Piano Analytics interface, providing complex data, metrics, properties, and reports to address the most important use cases in the media business

What Piano products do I need to have activated to use Subscription Insights?

The only requirement is Composer. While using Subs billing (Piano's subscription management tool) to process payments can result in richer data with less effort from the client's side, clients who use Linked Terms, Custom Terms, or forgo terms entirely can still use Subscription Insights effectively by sending conversion data from their own systems. To learn more about how to track conversions from third-party tools, please see this article, which outlines Subscription Insights implementation.

What are different Subscription Insights product variations?

Subscription Insights can used alone or can be fully utilized by implementing the Piano Analytics SDK, allowing data from two different sources to be combined. Additionally, clients can implement supplementary ARI and Content profiles. To learn more in details about all these options we do recommend to contact your account manager.

What is the difference between having fully licensed Piano Analytics vs Subscription Insights only?

Subscription Insights can be used alone or implemented alongside Piano Analytics by implementing the Piano Analytics SDK. Using the Piano Analytics SDK allows you to send non-Piano data through to Piano Analytics and use it as a full data model. This offers greater flexibility but requires additional implementation effort and will incur incremental costs, as it involves obtaining a full license for Piano Analytics.

With Subscription Insights alone, Piano owns both the data streaming and data model. All traffic data comes from the Composer SDK, and clients cannot modify the data model, add their own events, or customize properties. However, other than ensuring the data outlined here is no additional implementation is required, as Piano handles data quality and streaming.

What is the main difference between Composer reporting in dashboard and Subscription Insights?

A primary difference between Subscription Insights and Composer reporting in the dashboard is that Composer reports only allow you to see each individual experience, while Subscription Insights provides global reporting across all experiences. Subscription Insights also offers much more flexibility in manipulating the data, provides near real-time data, and includes significantly more data points than standard Composer reports.

What data is available within Subscription Insights?

Subscription Insights tracks the most valuable Composer actions, focusing on specific events like showOffer, showTemplate, and showForm exposures, along with subsequent events such as clicks and conversions. It also provides additional data points such as detailed user interactions, content consumption patterns, and propensity scores from predictive models, which are not available in standard Composer reports.

It captures events like page views, template exposures, clicks, conversions, and identity actions (e.g., logins). The data includes content metadata (authors, publication dates), template details (IDs, names, variants), user segmentation information (likelihood to subscribe or cancel), transactions (amounts, payment methods), and form interactions (exposures, submissions). This comprehensive dataset enables publishers to analyze user behavior, engagement, and conversions to optimize their experiences and drive revenue.

While the Subscription Insights data model is robust, actions like nonSiteAction, runJS, or template close actions are not streamed to Subscription Insights, nor are card executions that feed into the Flow report. This is because such data is would significantly increase event volumes and the associated cost to Piano clients.

For a more detailed understanding of the data available within Subscription Insights, see this documentation on the Subscription Insights data model.

How I should read Subscription Insights data in the context of Composer?

Composer is a tool for managing the acquisition journey and defining targeting strategies. In the context of Subscription Insights, the acquisition journey is tracked by gathering data on Template/Offer/Form exposures and visitor interactions, which are measured as clicks and conversions.

Exposures: In both Subscription Insights and Composer reports in the dashboard, exposures occur when an action card—showTemplate, showOffer, or showForm—is displayed. In Subscription Insights, this is logged as the event experience.action.
Clicks: Each time a visitor clicks on a specific object with external event tracking, the event is logged as experience.interaction in Subscription Insights. Subscription Insights includes deduplication logic, meaning if the same external event is executed multiple times, it is only logged once. The type of click is stored in Subscription Insights as "Interaction type".
Conversions: Conversions that come from Subs billing, such as subscription terms, registration terms, and gift term conversions, are logged in Subscription Insights as vx.conversion event. For clients using Linked Terms, conversion data is sent back to Piano, ensuring accurate revenue and conversion data in Subscription Insights.
- For clients using Custom Terms or forgoing terms entirely, conversions logged through Composer's conversion API are tracked in Subscription Insights as composer.conversion events. It's important to note that this API must have the "SentToCI" parameter set to "True" for the conversion to be tracked in Subscription Insights. For more information on this type of conversion tracking, see here.
- If a conversion event lacks site details, it is logged as vx.conversion.offsite in Subscription Insights. These offsite conversions can be analyzed in Subs billing reporting and Subscription Insights but cannot be attributed to any Composer experience and are thus not reflected in Composer dashboard reports. Custom term conversions, for example, would be logged as offsite conversions.

What if there are differences between Subscription Insights and Composer reports

Composer reports and Subscription Insights are built on top of the same data source. If there are data discrepancies, it will most often be caused by legitimate differences, such as differences in metric logic, differences in application settings, or differences in data processing. Minor differences should not be a major cause for concern.

Some common reasons the data may differ include:

Application in Composer Dashboard has different default timezone than Subscription Insights
In Subscription Insights the ECO mode is turned on. Eco Mode is a Piano Analytics feature designed to optimize performance and reduce environmental impact by using statistical approximations, resulting in faster data retrieval with a typical margin of error of less than 2%.
In Subscription Insights, you are using "Visitor level" metrics instead of "Event-based" metrics that are available in the Composer reports. Most standard Composer reports only have event-level data (number of template exposures, for example). Whereas within Subscription Insights you also have the option of visitor-level data (where there is the deduplication of events on browser ID).
- For example, if you look at “Exposures” in the Composer Conversion report and compare it to “Experience exposed visitors” in Subscription Insights, you will see a significant difference due to de-duplication at a visitor level. To see the event-based equivalent metric within Subscription Insights, you would instead want to look at “Experience action.”
Subscription Insights data is not retroactive, meaning that data begins populating in Subscription Insights once the implementation is complete. Composer and Subs billing data from before the implementation was completed will not be present, which can create data differences when looking over longer time ranges.
In Composer reports, you might analyze KPIs around action cards that are not integrated into Subscription Insights. Subscription Insights supports showTemplate, showOffer, and showForm action cards.
Conversions from 3rd party tools are logged without the specific Subscription Insights implementation as mentioned previous section. For more information on this type of conversion tracking, see here.
If you are looking at the current day’s data, Subscription Insights may have more up to date figures since its data processing completes in a few minutes while many Composer reports are batch processes that complete every four hours.

How I should read Subs billing data in the context of Subscription Insights

Subs billing is a subscription management tool that generates many events relevant for evaluating revenues, subscription growth, and active and passive churn. For acquisitions managed by Composer experiences, then most of the events are covered by Composer events mentioned in previous FAQs.

For new subscriptions or conversion of Subs billing type (registration term conversion, grant access, gift purchase, etc.) use vx.conversion event.
For new subscription that has been created in the system different way, e.g. telemarketing, or by migration/import, or does not contain on site data use vx.conversion.offsite event
To learn more about renewals and associated revenues use subscription.action.offsite event and filter the "Subscription Action" for renewal events
For active and passive churn, use the same subscription.action.offsite & subscription.action event "Subscription Action" for:
- Passive churn "Renewal failed, will retry" & "Renewal failed, will not retry"
- Active churn "Auto-renew disabled" & "Deferred canceled" & "Expired" & "Cancelled"

For clients using Linked Terms, accurate revenue numbers, conversion events, renewal events, and churn events must be sent to ensure the data appears properly in Subscription Insights.

What if there are differences between Subs billing reports and Subscription Insights

The possible reasons mentioned earlier for data differences mentioned for Composer reporting also apply for Subs billing reporting. There are also a few additional legitimate reasons for differences:

Application in Composer Dashboard has different default timezone than Subscription Insights
In Subscription Insights the ECO mode is turned on. Eco Mode is a Piano Analytics feature designed to optimize performance and reduce environmental impact by using statistical approximations, resulting in faster data retrieval with a typical margin of error of less than 2%.
Ensure you are comparing the correct KPI aggregation. Much of the confusion in Subs billing comes from the fact that one user can have multiple subscriptions, and we differentiate between "Subscriber = user" and "Subscription" level reporting. If you go to "Mine Users" and ask the tool to generate the total number of users with a specific action, then you need to select the corresponding metric in Subscription Insights at the user level. Within Subscription Insights and Piano Analytics “user” is defined as a known user with a user ID.
In Subs billing, most reporting is focused on the current snapshot of the subscription base so you can retrieve the list of current and former subscribers over all time. Subscription Insights, by contrast, collects information on events around subscriptions and Subs billingin real-time rather than looking historically. In Subscription Insights, you can retrieve data, for example, on how many subscriptions were renewed in the past week.
If the revenues in the dashboard platform differ from Subscription Insights, it might be because you are using automatic currency conversion in Subscription Insights. This is a significant benefit in Subscription Insights because you have all revenues in one metric to monitor topline performance. Subs billing reports keep revenues in the original currency because this is required for financial reporting. For financial reporting purposes, Subs billing reports should remain the source of truth.

Is data from the Piano propensity models available within Analytics?

Yes, they are available as part of the standard Subscription Insights model. To get these data populated to Subscription Insights, client needs to collect data via Composer SDK and use these segments in live experiences with action cards show Template or show Offer. More details available in our data model

Are we able to attribute content that lead to paid subscription?

Yes, there are two ways of attributing the content to conversion event.

If the checkout process is indirect and leads through the landing page, we offer solution with "ptid" parameter.
Additionally to "ptid" solution, we have build the "Content that converts" feature which attributes the conversion to the last article read before the conversion event. To make this feature work the content type tagging needs to be defined.

How can we send custom events?

To integrate to Subscription Insights custom events, the client needs to have activated Subscription Insights and Piano Analytics. To learn more in details about all these options we do recommend to contact your account manager.

What reporting is available for Site Licensing

Site Licensing is Subs billing feature that allows to create a Site license on behalf of a client via the Piano dashboard. These licenses will allow any users associated with the contract to redeem access to your site by visiting a landing page and registering. In Subscription Insights we do support site licensing reporting for different analytical use cases:

Site licensing audience segmentation: Each site licensing visitor who is logged in can be identified in Subscription Insights using property "Has access to Term type" or "Has access to Term name". Thanks to these audience segmentation, you are able to identify main attributes of site licensing visitor such as geo location details, technology, traffic sources, engagement levels but mostly, their editorial preferences.
Site licensing access redemption: For customers who receive an offer to redeem access, we track these events. You can analyze redemptions as conversion events where the property 'Goal type' is set to 'Licensee contract converted.' Additionally, you can cross-reference these conversion events with any on-site property you need.

Where can I find data about active subscribers?

For analyzing the number of active subscribers or active subscriptions please use the new measurement metrics available in data model.

To analyze the total volume of subscribers on page, use the property `Has access to Term type` or `Has access to Term name` to filter out active subscribers on specific term type or term and use metric "Users"

If property `Has access to term/term type` is not available, please check this article

How I can export data from Subscription Insights?

Data can be downloaded in Piano Analytics interface to CSV but if you need more systematic exports, here are two ways:

For aggregated data, even down to event-level:

Reporting API, incl. a dynamic API request builder GUI via drag and drop data mining in Data Query: 1 Product tour
Automated CSV delivery (to sFTP, S3)

For raw event-level data:

Data Flow: Data Flow
Data Sharing via Snowflake, either in Piano’s Snowflake account or in your own Snowflake account: Introduction, Data Schema & Access

The Data Adaptor forwards events from Piano Activation to Piano Analytics according to the following consent mode rules:

if consent mode = “opt-in” or “custom” then visitor_privacy_mode=optin
if mode = “essential” then visitor_privacy_mode=extended-optout
if mode = “opt-out” then visitor_privacy_mode=extended-optout

If you use a custom consent mode, it will be processed based on the default consent mode it derives from (opt-in, essential, or opt-out).

Data collected from essential and opt-out will still be available in Piano Analytics, but in anonymized form.

Which Subscription Performance tiles require Active Churn Prevention (ACP)?

Several tiles on the Subscription Performance board are populated exclusively from data collected via Templates run by Active Churn Prevention (ACP). Without ACP active on the site, these tiles will be empty regardless of how the rest of Subscription Insights is configured:

Likelihood to Cancel
Churn Prevention
Active Churn

If you see these tiles empty and the rest of the board populated, the cause is almost always that ACP isn't running on the site. ACP is a separate Piano capability; contact your account representative to discuss enabling it.

How do I track custom conversion events with Subscription Insights?

Conversions tied to a Composer Show template card are not tracked automatically — they need to be explicitly configured as custom events. For each conversion action you want to measure (registration completion, newsletter signup, account activation, and so on):

Define the custom event in your Composer template configuration (typically via the external-event directive on a CTA, or via the external conversion API).
When using the external conversion API, set the SendToCI parameter so the event is pushed through to Subscription Insights. Without this parameter, the event is logged in Composer only and never reaches Piano Analytics.
Validate in the Acquisition Performance board that the custom conversion is being counted under "Experience Converted Visitors."

How does "Content Spread on Conversion" work?

Content Spread on Conversion is an Subscription Insights feature that automatically propagates the most recent article context to the conversion event, so the conversion can be attributed to the content that influenced it — even when the conversion itself happens on a different page (a checkout, an offsite landing page, an email-confirmed purchase).

The feature is built on the same mechanism as the _ptid tracking parameter and the "Content that converts" attribution model: the last viewed article identifier is carried forward with the visitor and attached to the conversion event when it fires. Enabling Content Spread on Conversion requires the content tagging on your site to include the article identifier and content type properties; without these, the attribution falls back to whatever the conversion event itself carried.

How do I track the same subscribers across term changes and promotions?

When subscribers move between terms — for example, an annual renewal following a monthly promotional term — Subscription Insights provides several ways to follow them:

By term over time. The Subscription Performance board's "Active subscriptions over time" and "Revenue by term" tiles show movement between terms within the same site.
By promotion. The Acquisition Performance board's payment-conversion charts distinguish between new conversions on a term vs. renewals, and let you filter by the Promotion ID associated with the conversion.
In Data Query. For richer analysis, build a custom Data Query report that joins vx.conversion events on visitor ID, with the Promotion ID and term billing period as breakdowns. This lets you count, for any cohort of subscribers, how many renewed on the same term, moved to a different term, or converted originally via a specific promotion.

Why are my revenue numbers different in the Piano API vs. Subscription Insights?

The subscriptions table accessible via the Piano API can include amounts with tax, while the Subscription Insights revenue metrics typically exclude tax. Comparing the two directly will overstate API revenue relative to SBI revenue by the tax rate.

When you need an authoritative revenue figure:

For dashboards and reporting in Piano Analytics, use the SBI revenue metrics directly (Experience Revenue, Subs billing turnover, New Subs billing turnover).
For reconciliation against finance systems, work from the API but apply your own tax exclusion logic, or use the dedicated revenue endpoints that return tax-exclusive amounts.

In all cases, document which definition you used in the report so future consumers know what to compare against.