Stripe Billing Integration

Overview

Piano's Stripe Billing integration combines Piano's flexible subscription management with Stripe's advanced billing infrastructure and AI-powered revenue recovery capabilities. This integration maintains Piano as your primary interface for subscription operations while leveraging Stripe's billing engine to handle payment processing, invoicing, and automated retry logic.

The Piano Subscription Management + Billing integration is now fully released and supports clients using Stripe Payments and Non-Stripe payment providers.

QuickStart Guide

Enabling Stripe Billing

The Stripe Billing integration needs to be enabled on your application by your Piano representative. Clients will be enabled in turn based on their use of Piano features. Contact your Piano representative if you have any questions.

Existing Stripe Payments clients

Your existing Stripe account used for Payments will be automatically connected to Piano's Stripe Billing Connect account if you have previously connected it, you only need to add your Stripe API keys. There is no additional setup required in Piano. You simply need to log in to your Stripe Dashboard and complete the configuration steps below.

New to Stripe Payments Clients

New Stripe clients need to create a Stripe account before configuration.

1. First create your Stripe Account (you can do this in your Piano Dashboard/Stripe Billing configuration), then configure Stripe Account and Business settings

2. Connect your Stripe Account to Piano as described in Stripe Billing Configuration in Piano (if the Stripe account was created outside Piano)

3. Follow the steps for Stripe Dashboard configurations below

Non-Stripe Payments Clients

Clients who do not use Stripe for Payments, also need to create new Stripe account. Please contact your Piano representative to enable your Stripe Billing integration.

Required Stripe Dashboard Configuration

The Piano-Stripe integration requires a few simple configuration changes in the Stripe Dashboard so that subscriptions can be fully synchronized between the two systems. Below is an overview for both Stripe Payments and BYOP clients. 

For BYOP clients, the same settings apply as above, except Revenue Recovery settings which are not applicable to BYOP subscriptions. Please make sure to review both the Manage Failed Payments and Manage invoices sent to customers sections.  

Below, you'll find the same configuration steps outlined in a step-by-step format.

Billing Settings

Revenue Recovery Settings (Only Stripe Payments clients)

In the Stripe Dashboard, navigate to Settings → Billing → Subscriptions → Revenue Recovery → Retries → Cards.

Recommended configuration:

• Retry period: 2 weeks (to avoid overlapping periods on monthly subscriptions). Choose to retry up to 8 times in the period for best recovery results.

• Subscription status: "Mark the subscription as unpaid"

• Invoice status: "Mark the invoice as uncollectible"

This setting configures the same retry rules regardless of term length. To use different rules for monthly vs. annual subscriptions, use Automations to configure separate policies.

In the same section, navigate to Local Payment methods and click Manage to enable retries accordingly (e.g. if you use SEPA or other direct debit payment methods). 

Invoice Settings

Invoice Finalization Rules

In the Stripe Dashboard, navigate to Settings → Billing → Invoices → Invoice finalization period and locate the Edit button next to the default rule.

Required setting:

• Set finalization grace period to 1 hour (default)

• Do not add additional rules

Upcoming Invoice Events

In the Stripe Dashboard, navigate to Settings → Billing → Subscriptions and emails → Prevent Failed Events → Upcoming renewal events.

Required setting:

Configure events for upcoming renewals to ensure proper validation between Piano and Stripe — this is an important integration point between the systems. Change the "Upcoming renewal events" setting to be triggered 3 days before a subscription renews.

Invoice Level Rounding

In the Stripe Dashboard, navigate to Settings → Billing → Invoices → Manual tax amount rounding.

Required setting:

If you use Piano Tax support, choose "Round manually entered taxes at invoice level". This ensures that the Invoice level rounding rules are enabled in your Stripe account Invoice settings to prevent discrepancies.

Disable Automatic Invoice Emails (Only Applicable to Non-Stripe Payments Clients)

To prevent customers from paying directly on Stripe when using a non-Stripe processor, disable automatic notifications.

In the Stripe Dashboard, navigate to Settings → Billing → Subscriptions and emails → Manage invoices sent to customers and disable the customer emails toggle for Send finalized invoices and credit notes to customers.

Stripe Payments customers can leave this enabled if desired. Make sure Stripe email rules and Piano Email Manager do not conflict or send duplicate emails. For BYOP clients, ensure no payment links are enabled on invoices — otherwise there may be double charges.

Manage Failed Payments setting

Under Settings → Billing → Subscriptions and emails, navigate to Manage Failed Payment and update the Subscription status to Unpaid and Invoice Status to Uncollectible.  

Manage Invoices Sent to Customers (Only Applicable to Non-Stripe Payments Clients)

In the Stripe Dashboard, navigate to Settings → Billing → Subscriptions and emails → Manage invoices sent to customers and update the Subscription status to Unpaid and Invoice Status to Uncollectible. These settings apply to BYOP invoices since they use collection_method = send_invoice. 

This is important to ensure Piano can manage BYOP grace and retry logic and handle cancellation, in no case set the Subscription status to Cancel.

Stripe Billing Configuration in Piano

Stripe Account Configuration in Piano

There may be multiple account hierarchy use cases; such as 1 to 1, 1:2 and many to 1 scenario between Piano and Stripe applications and account structures. It is important to understand the effect of multiple account configurations.

Known limitations: Stripe doesn’t currently support sharing customers and payment methods across multiple connected accounts!

Scenario 1: 1 to 1 (Supported and recommended)

Most common implementation scenario, fully supported and recommended.

Scenario 2: Many Piano apps to 1 Stripe account (Supported)

Using a single Stripe account for payment processing across multiple Piano applications is supported.

Scenario 3: 1 Piano app to 2 Stripe accounts (Unsupported DO NOT USE!)

Using multiple Stripe payment integrations connected under the same application in Piano with two different Stripe accounts for processing payments is not supported and should never be used.

How to connect Piano with Stripe Billing

Creating a new Stripe Account

You need to create Stripe account for Billing purposes even if you do not use Stripe for Payments. To do that, navigate to Piano Dashboard → Edit Business → Stripe Billing configuration → click Add and then Connect:

This will trigger Stripe onboarding flow:

Follow the instructions in the flow to create an account.

Connecting an existing Stripe Account

Clients using Stripe payments have their accounts connected automatically and presented in the Billing configuration already. If your Stripe API keys are not already added in the Payment Provider configuration, you will need to add them to connect Stripe Billing,. In case you have not yet connected your Stripe account, you will need to "Connect" in Piano.

Piano will use the account ID from your Stripe payment provider configuration to make sure that your customers and payment methods information already created in the application will be used with Billing.

In the Piano Dashboard, navigate to Edit Business → Billing Provider and click Add and then Connect to trigger the Stripe onboarding flow to authenticate your Stripe Account.

The Stripe Billing configuration is ready to use when BOTH Connected Account ID and API credentials are populated and valid.

To get your Stripe API credentials, navigate to the Stripe dashboard and login. On your Home page you can find your API keys in the top right corner:

In case you cannot see the keys on your Home page, you can also find them in the Settings → Developers → API Keys – select the Standard API keys, do not use restricted keys as these may lead to loss of functionality.

Clients already using Stripe for payments, but Stripe account is not yet connected

Clients need to connect their account for Stripe billing using Stripe billing configuration. In this case, their Stripe payment provider integrations won’t be affected.

Stripe Account for Billing additional considerations

• Once your Stripe account is connected to Piano and used for billing, you cannot change it in Stripe payment provider configuration nor in Stripe billing provider configuration. To switch to a different account, a migration on both Piano and Stripe side will be required. It is NOT recommended to change accounts in the application once connected.

• The same connected account used across different Piano applications doesn’t guarantee that billing configurations will be created for each application. To switch all applications to Stripe, make sure each application has Stripe Billing configured.

• After the application has been switched to Stripe billing, all new connections to Stripe made with payment provider integrations will use the same connected account ID from the Billing configuration.

• To disconnect already connected accounts from Piano, clients need to inform their Piano and Stripe Account representatives to help organize the process of disconnecting without losing or corrupting any information.

Stripe Dashboard Navigation

Stripe dashboard can be accessed via https://dashboard.stripe.com/ for both production and sandbox instances. For more details on how Piano regional instances are connected to Stripe accounts see docs.

We recommend you learn about Stripe Dashboard features and settings. Some of those features are explained below and you should review the full Stripe documentation.

Below is a brief overview of the key places where Piano- created entities will appear.

Once you login, you will see the following view.

Home view

Transactions view

The most important and relevant tabs to navigate are Transactions, Customers, and Subscriptions. You may already be familiar with Transactions and Customers if you use Stripe for payments:

Transactions tab shows all payments executed for customers; this is what clients using Stripe Payments typically see and use, in addition to the Customers tab.

Customers view

Product Catalog view

Product Catalog stores Piano Resources and Tax Rates as Stripe Billing entities; it will show any Piano Resources converted on.

Each Product will include Piano Metadata, which should not be edited in Stripe, for more details on Metadata please see the section below.

Tax rates

Under the Tax Rates tab, clients using any of the Piano Tax support and its integrations will see manual tax rates created there automatically on any switched or newly purchased products. Do not make changes to the tax rates in Stripe; these are programmatically maintained and in sync with Piano Tax support.

Automatic Stripe Tax is not supported in the current phase and must not be enabled at this time as it will lead to conflicts across entities and integration.

Example with Piano created tax rates (these must not be changed in Stripe at any time)!:

Invoices

The Invoices tab shows all invoices for every customer and the status of each billing operation on subscriptions:

When the invoice payment is being retried, the status is updated at the individual invoice level.

Subscriptions view

Subscriptions tab will include all subscriptions including any Piano subscriptions switched to Stripe Billing and newly purchased subscriptions after Billing integration is enabled. Clicking on a subscription in the list shows details including customer email, resource (Stripe product), price, tax rate and amount, access period and a preview of the customer’s next invoice:

All of the associated data is maintained in sync with Piano. Metadata provides additional Piano context.

Out-of-sync recovery

In case a discrepancy occurs during validations, Piano will automatically cross-check all relevant states and entities to automatically correct and update the subscription as necessary to finalize the invoice accurately.

If you use Stripe Billing to directly manipulate Piano-managed Product catalog, Subscriptions or Invoices and Piano cannot cross-check entities (e.g. you create new product and/or price and add it to subscription directly in Stripe), such subscriptions will become out-of-sync. For any out-of-sync subscriptions, Piano will stop managing subscription billing and collection and will no longer show accurate subscription and transaction data and events in the Piano Dashboard.

Currently, Piano will retain active access for the customer, but the subscription will no longer be manageable in Piano and all operations except cancelation will be limited in the Piano Dashboard. Piano will keep extending access to the original subscription resource(s) only while the subscription is active in Stripe.

In case such a situation occurs, you will see a notification in the Subscription details view of such subscription as per below:

In case an out-of-sync happened from unexpected reasons (e.g. human error), please contact the Piano support team immediately and Piano support can reinstate the subscription state to make it in-sync again.

Piano monitors for data inconsistencies between its records and Stripe. If a discrepancy is identified, your Piano account team will contact you to coordinate resolution. Fully automated reconciliation is planned for a future release. 

Feature Overview

New Purchases

Piano integrates existing features, including payment and checkout interfaces with Stripe Billing in addition to Stripe Payments. Overall, existing Piano dashboard and functionality will remain unchanged, unless specified.

Any new subscriptions created in Stripe Billing from a purchase in Piano Checkout or Subscribe User in the Piano Customer Service dashboard will show two transactions in the Stripe dashboard, one in ‘Cancelled’ state and one in ‘Succeeded’.

This is an expected behavior and a result of using Stripe API operations during subscription creation. At this time Stripe is not able to remove this record appearing in the dashboard, and Piano is not able to change it. This duplicated record listing is purely visual and has no impact on any subscription processing or billing. The correct payment is associated with the newly created subscription invoice. Subscribers will only see a single transaction in the Piano Dashboard and on their credit card or bank statement.

Currently, the following new purchase features are supported. For the list of unsupported features, please refer to Piano unsupported features in this section.

Resources

• Resource creation (mapped to Product in Stripe)

• Resources are mapped 1:1, but are not created in Stripe immediately/real-time when a new Resource is created in Piano. When a new subscription conversion is passed from Piano to Stripe, the Resource is looked up. If it doesn't exist in the Stripe Product Catalog, a new Stripe Product is created and mapped to the Piano Resource.

Payment Terms

• Single payment (one-offs, mapped to price_data) or Recurring payment (mapped to price_data and subscription schedule)

• Support for shared access (buyer and subscription in Billing)

• Allow users to pay more

• Trials (Paid trial and free trial periods, presented as 0 amount schedule phases in Stripe for free trials)

• Promotions (Paid and free promotions, presented as net amount schedule phases)

• Apply trial period for new customers only

• Force all new subscriptions to be auto-renewing subscriptions

• Restrict to first-time customers only

• Gift purchase creates Stripe Invoice with purchase-date service period

• Stripe recognizes gift revenue immediately based on invoice service period (purchase date)

• Gift redemption remains fully handled by Piano

• Every new one‑time payment creates a Stripe Invoice

• Upgrades immediate and deferred (for more details see the Upgrades section)

Tax Support

Tax calculations made with Piano Checkout and Subscribe User tools will be used to automatically create unique manual tax rates in Stripe Billing and apply those rates to invoices and subscriptions. Likewise, any existing subscriptions will be created with manual tax rates, if you use Piano Tax support.

Rounding Rules: Generally, tax amounts calculated separately by 3rd party system may differ slightly from tax amounts applied to invoices with manual tax rates pre-created in Stripe (usually 0.01 in the smallest currency unit). That difference might take place in case of different rounding rules between the two systems applied to exclusive tax rates. For more details, see the Rounding Rules docs.

You must configure the "Invoice level" rounding in case you use Piano tax support with any tax provider. Ensure that the Invoice level rounding rules are enabled in your Stripe account Invoice settings to prevent discrepancy.

Checkout

Once you’ve configured Stripe Payments and Billing in your Piano application, you will be able to see subscriptions and purchases represented in the Stripe Dashboard.

The initial purchase is processed in Piano and then a subscription and/or invoice (one-offs) is created in Stripe Billing. From this moment on, Stripe Billing manages the billing process.

Stripe Cards, Stripe Elements, and Stripe Apple Pay are supported for checkout with Stripe-native billing. Non-Stripe payment providers are supported via Piano's BYOP feature — see the Non-Stripe Providers (BYOP) section for details. No changes are required in the system templates.

Subscribe User (via Piano Dashboard)

Subscription purchases made within the scope of supported features for this phase automatically create subscriptions and associated invoices in Stripe Billing.

Subscription Operations

The following Piano subscription management features are supported within the integration for Stripe managed subscriptions.

Update renewal payment method and billing address

The functionality to update payment method or billing address remains available and functions as it always has.

Changing payment method between Stripe and non-Stripe providers is supported via Piano's BYOP (Bring Your Own Processor) feature. See the Non-Stripe Providers (BYOP) section for full details.

Auto-renew toggle on/off

You can easily control whether a subscription renews automatically at the end of its term.

Turning Auto-Renewal OFF:When you disable auto-renewal, the system modifies the subscription billing plan to set a definitive end date—the end of the current paid period. This instructs the billing system not to generate any future invoices, ensuring the subscriber will not be charged again.

Turning Auto-Renewal ON: If you re-enable auto-renewal, the system removes that end date and restores the subscription's original, ongoing billing plan. The subscriber will be charged on their next scheduled billing date as if the setting was never changed.

Turning off auto-renewal during a grace period

When a subscriber turns off auto-renewal while their subscription is already in a grace period (a renewal payment failed and retry attempts are still running), the cancellation is deferred to the end of the current billing period — it does not take effect immediately.

Because the cancellation is deferred, payment retries continue for the open invoice throughout the remainder of the grace period. This means a retry can succeed after the subscriber has turned auto-renewal off. If the charge goes through and the subscriber did not intend it, it should be remediated with a refund.

This behavior applies to all subscriptions on Stripe Billing — both Stripe-native payment methods and BYOP (Bring Your Own Payment) integrations.

What happens step by step

1. A scheduled renewal payment fails. The subscription enters a grace period: access is retained while retries run.

2. During the grace period, the subscriber turns auto-renewal off.

3. The cancellation is scheduled for the end of the current billing period. The subscription is not cancelled immediately, and the open invoice is not voided.

4. Retries continue against the open invoice for the remainder of the grace period. If a retry succeeds, the payment is collected and the subscription is extended as normal — even though auto-renewal has been turned off. The deferred cancellation then takes effect at the next renewal date.

5. If the subscriber is charged unexpectedly, issue a refund.

The practical effect: turning auto-renewal off in a grace period stops future renewals but does not stop the in-flight retry of the currently failing payment.

BYOP note: BYOP subscriptions follow the same deferred-cancellation logic. The difference is that Piano drives the retries directly (rather than Stripe Smart Retries) and marks the invoice paid out-of-band on success.

Immediate subscription cancellation

You can cancel a subscription at any time, with the cancellation taking effect immediately.

Cancellation without a Refund: This is a direct action. Our system sends a command to immediately terminate the subscription in the billing system. Access is revoked, and all future scheduled charges are stopped.

Cancellation with a Refund: This is a two-step process to ensure financial accuracy. Our refund process remains unchanged.

First, the refund is issued through the standard process.

Once the refund is successfully processed, the system then proceeds to cancel the subscription. This sequence prevents situations where a subscription is cancelled before a refund can be properly issued.

Refunds (full and partial)

Supported, refunds are automatically reflected in Stripe, for BYOP subscriptions invoice credit notes will also be applied to accurately adjust revenue recognition in Stripe.

Changing a Subscriber's Next Billing Date

You have the full flexibility to adjust when a subscriber is next charged, either to provide a complimentary service period or to align billing dates.

When you change a subscriber's next billing date in Piano, our system adjusts their billing schedule in Stripe. We effectively end their current paid period and insert a new, complimentary (zero-price) phase that runs from the moment of the change until the new billing date you've selected. Regular billing then resumes on that new date.

Important Caveat: Because Piano creates a complimentary period to bridge the gap, if you view the subscription directly in the Stripe dashboard, you might notice it temporarily reflects a $0 price until the new billing date arrives. This is the expected behavior.

Please note: currently changing the next billing date is only supported up to 3 years ahead. Stripe Price objects only support 3-year billing intervals as maximum at the moment due to risk and chargebacks typically associated with longer billing periods.

Manual Renewal

The core Manual renewal flow in MyAccount and Dashboard is supported for Stripe payment methods (Stripe CC, Stripe Elements sync, Stripe Apple Pay) and BYOP payment methods. This covers both pre-billing renewal and grace-period escape scenarios.

Upgrading and Downgrading

For more details on Upgrades, please see the Upgrades section below. For deferred upgrades, publishers can manage the lifecycle with the following operations:

Supported payment methods within the Stripe integrations

Stripe payment integrations (Stripe Elements, Stripe Cards, Stripe Apple Pay) are fully supported as per documentation. Non-Stripe payment providers are supported via Piano's BYOP (Bring Your Own Processor) feature — see the Non-Stripe Providers (BYOP) section for configuration details below.

Payment method management

Non-Stripe Providers (BYOP)

BYOP (Bring Your Own Processor) enables clients to continue using their existing non-Stripe payment processor — such as Braintree or Datatrans — while Piano manages the full subscription lifecycle through Stripe Billing. In this model, Stripe acts as the subscription engine (schedules, invoices, renewal logic), while your processor handles the actual charge.

This means you get Stripe Billing's invoice and subscription scheduling — combined with your existing payment infrastructure. Note: Stripe Smart Retries only support Stripe-native payment methods. For BYOP subscriptions, Churn Prevention configured grace period and retry logic applies and continues to be managed in Piano and your processor as per the specification of your PSP integration in Piano.

BYOP renewal flow

The key difference in BYOP is which Stripe webhook event triggers subscription renewal in Piano. With Stripe-native payments, the invoice.paid event signals successful collection. With BYOP, the invoice.finalized event is used instead, since the actual payment is collected “out-of-band” by your processor.

BYOP vs Stripe-native comparison

Subscription Payment method changes

Clients can switch a subscriber's payment method between Stripe-native and BYOP within Piano. When switching, Piano updates the subscription's billing context and ensures the correct renewal trigger (invoice.paid vs invoice.finalized) is applied going forward. This transition is handled transparently without interrupting the subscriber's access.

Grace period

For BYOP subscriptions, the grace period is managed by Piano rather than Stripe Smart Retries. When invoice.finalized is received and your processor has not yet confirmed payment, Piano extends subscriber access for the configured grace period while your processor retries the charge. If the charge is not collected within the grace period, Piano expires the subscription.

Payment method management

Non-Stripe payment methods are stored as references in Piano. When a subscriber updates their payment method in MyAccount, the token is updated in your processor and the reference is updated in Piano. Stripe does not hold the actual payment method for BYOP subscribers.

Multi-currency and multi-customer support

Piano fully supports subscribers transacting in multiple currencies. Because Stripe requires a separate customer object per currency, Piano automatically creates and manages additional Stripe customer records where needed. This happens transparently — from your perspective, there is one subscriber; Piano handles the Stripe-side customer mapping.

This applies equally to both Stripe-native and BYOP subscribers. Your existing multi-currency business rules continue to operate as configured in Piano. In case of multiple concurrently active subscriptions in different currencies on a single subscriber, user will be asked to select currency in the MyAccount to ensure the payment method is properly associated with customer and currency in Stripe.

BYOP subscription operations

All standard Piano subscription management operations are available for BYOP subscriptions:

• Auto-renew toggle on/off

• Immediate cancellation (with or without refund)

• Changing next billing date

• Payment method update (updating token reference in your processor)

• Subscription switching between BYOP and Stripe-native (in case you use both)

Upgrade operations for BYOP

Upgrade and downgrade operations for BYOP subscriptions follow the same 2:1 mapping as Stripe-native upgrades: Piano cancels the existing subscription and creates a new one with the target term and a proration credit applied, while in Stripe Billing subscription remains the same and a result of upgrade or downgrade is represented as an updated subscription Schedule period only, effectively retaining the same subscription. Piano calculates the proration amount, which is applied as net amount to the specified subscription schedule phase in Stripe.

Subscription Upgrades

Subscription upgrades — moving a subscriber from one term to another — are now available for all Stripe Billing managed subscriptions. Upgrades are being released concurrently with BYOP, so both capabilities are available from day one.

Upgrade model: Stripe subscription-first

Piano now uses Stripe’s subscription-first model for all upgrades. This means:

• The subscription plan change is applied to Stripe immediately when an upgrade is initiated, subscription remains the same in Stripe.

• Payment is collected after the subscription change — not as a prerequisite to it.

• If payment fails, the subscriber enters a grace period with Stripe Smart Retries — the subscription change is NOT rolled back.

• All upgrade channels (My Account, Checkout, Publisher Dashboard, API, Action Manager) behave identically.

Note: This is a behavioral change from legacy Piano billing, where immediate upgrades made via MyAccount, Dashboard and API resulted in a rollback (no charge, no change) but not Onsite Upgrades which already follow the subscription-first model. Publishers who rely on that rollback behavior should review their downstream integrations.

Supported upgrade types

• Immediate upgrade (billing_timing=0): The plan change and payment happen at the moment of the upgrade request. Stripe creates a two-phase Subscription Schedule — Phase 1 ends immediately, Phase 2 (new plan) starts with a prorated charge.

• End-of-billing-cycle upgrade (billing_timing=1): The plan change is scheduled to take effect at the end of the current billing period. Stripe creates a Phase 1 (current plan, runs to period end) and Phase 2 (new plan, starts at period end).

• Payment-to-payment only: Only upgrades between payment term subscriptions are supported. Dynamic-to-payment and Scheduled-to-payment upgrade offers are not supported and must be disabled before switching.

• Same currency: Stripe subscription currency is immutable. Cross-currency upgrades are not supported.

• Pending upgrades: Subscriptions with an already scheduled (deferred) upgrade will not be switched to Stripe Billing until that upgrade executes or is cancelled.

Proration and payment collection

Piano calculates all proration amounts before passing them to Stripe. The proration logic is unchanged from legacy Piano billing.

Payment is collected off-session: there is no in-session payment step during the upgrade. Stripe charges the subscription’s default payment method automatically, in case of failure starts Smart Retries, else Piano starts Churn prevention on BYOP subscriptions.

Payment failure handling

If an upgrade payment fails, behavior depends on the payment method type:

• Stripe-native and BYOP synchronous methods: Grace period starts with Piano Churn prevention on BYOP or Stripe Smart Retries attempt recovery for up to 8 retries over a configurable window on Stripe native methods. If all retries fail, the subscription follows the configured dunning policy. The subscriber retains upgraded plan access during the grace period.

• BYOP asynchronous methods (direct debit, bank transfer): Payment failure results in immediate subscription cancellation — no grace period. Access is granted at upgrade time but revoked when the async failure is confirmed. This matches legacy Piano behavior for BYOP async. See BYOP Upgrade Operations above.

Pending upgrade management

All lifecycle operations for deferred (end-of-billing-cycle) upgrades are supported:

• Cancel pending upgrade: The Stripe Subscription Schedule is released. Phase 2 is discarded, the subscription continues on its current plan, and auto-renewal is restored.

• Suspend pending upgrade: The subscriber turns off auto-renewal while an upgrade is pending. The Stripe schedule end_behavior is set to cancel — if not resumed, the subscription will expire at period end.

• Resume pending upgrade: Auto-renewal is re-enabled. The Stripe schedule is restored with Phase 1 + Phase 2.

• Abort (automatic): If a suspended upgrade reaches the billing period end without being resumed, Stripe expires the subscription. The subscription transitions to Expires at End (EWE) and no publisher action is required.

Shared account upgrades

Upgrades for shared account (family/team) subscriptions are supported with no additional configuration required.

Supported features overview

Upgrade behavior with asynchronous payments

When an upgrade is paid with an asynchronous payment method, Piano's webhooks, history events, and emails behave differently under the Stripe Billing integration than they did under the legacy billing engine. Previously, Piano confirmed the upgrade as finished at the moment it was initiated, even though the payment was still processing. Now, Piano separates the initiation of the term change from the confirmation of payment.

At the moment of upgrade, Piano sends a new "initiated" webhook set, alongside the existing payment_pending.payment_pending:

• term_change.term_change_initiated

• subscription_ended.term_change_initiated

• subscription_created.term_change_initiated

• access_revoked.term_change_initiated

• access_granted.term_change_initiated

These reflect that the term change has taken effect while payment is still processing.

Once payment succeeds, Piano sends term_change.term_change_finished and payment_completed.payment_completed to confirm completion.

If payment fails, behavior depends on whether a grace period is configured. Under the legacy billing engine, a failed payment expired the subscription immediately, with no grace period available. Under the Stripe Billing integration, if a grace period is configured, Piano instead sends term_change.term_change_failure and term_change.term_change_grace_period_started, then falls back to the same webhook sequence used for synchronous-payment upgrades once the grace period resolves (through retry success or final failure).

This change also affects what users and publishers see directly:

• History events: MyAccount and the Publisher Dashboard display new history events describing the pending/initiated upgrade state, for upgrades triggered from either MyAccount or the Publisher Dashboard.

• Emails: If payment fails and a grace period is configured, users receive the standard "Subscription renewal failure" email rather than "Term change failure." Note that the grace-period paragraph within that email is intentionally suppressed in this case.

Subscription Billing

Once you have enabled Stripe Billing integration, all new purchases will result in subscription creation in Stripe, and renewals will be managed by Stripe going forward.

Revenue Recovery (Smart retries)

Clients using Stripe Payments and Billing will be able to benefit from the latest AI/ML driven retry processing which operates across cards, card-based methods and direct debits, with a 56%+ success recovery rate across failed payments. Stripe achieves this success rate because of the high volume of payments processed – 90% of cards have been seen on the Stripe network before, and Stripe stores and learns from global payment success and failure patterns.

Because Stripe uses AI/ML to power Smart retries, retry patterns will differ compared with Piano Passive Churn or other preconfigured static retry methods. One result is that there is not a set grace period, and while next attempt dates are provided with every failure, these may change depending on the opportunity to retry and success signals Stripe sees for the card across the network.

Passive Churn vs Revenue Recovery (Smart Retries) Differences

Email Notifications

Existing notifications will continue to be sent even for Smart retries. As of right now, only a single renewal failure notification is available. Additional email dunning configuration are expected in later phase.

Renewal retries processing

Understanding the renewal and retry logic when using Stripe Revenue Recovery includes two key failed renewal processes:

Synchronous Payments (e.g. Cards, Apple Pay, Google Pay):

1. Renewal date arrives

2. Payment attempt made immediately

3. If successful: subscription renewed, access continued

4. If failed: Smart Retry begins, access extended until next billing date during retry period

Asynchronous Payments (e.g. Direct Debit):

1. Invoice created and finalized

2. Subscription renewed, access granted

3. Payment collection initiated

4. If payment fails: Smart Retry begins while Piano is maintaining access until the next billing date

Hard Decline handling

On any hard decline, Stripe starts Smart Retries, Piano starts grace period and sends a renewal failed notification, expecting the end-user to go to MyAccount and add a new payment method which updates the subscription default payment method in Stripe. Then Stripe tries to charge against the invoice and if the payment fails it continues Smart retries cadence as configured in Revenue Recovery settings, until successful or terminal failure resolution.

For more details on which hard declines do not trigger charges in Stripe Smart Retries until a new payment method is provided, see the Stripe docs for more details.

Payment Action Required

In some rare cases, additional authentication may be required during renewal payments, for example with 3DS re-authentication. If a renewal payment fails, the subscriber is directed to their account page to update their payment method and re-authorize the payment.

In these cases, Piano receives a Stripe payment_action_required error event, so Smart Retries do not start automatically. Instead, Piano initiates a fixed 30-day grace period and sends a Subscription Renewal Failure email every five days, up to six times, or until the payment method is updated in My Account. Once updated and re-authorized, Stripe attempts payment for the outstanding invoice, and the normal flow resumes, including Smart Retries if applicable.

Key Stripe Dashboard configurations

Revenue Recovery Settings

There are two options to configure your Revenue Recovery in Stripe Billing.

1. General Revenue Recovery settings enable configuring one global retry strategy for all subscriptions. You have the option to use Smart Retry or a fixed custom retry policy, and the option to turn on retries for Bank debits. Direct Debit retries have a preset duration and number of attempts following the bank guidelines. Piano recommends using both Smart Retry and Bank debit retries.

2. Automations settings enable configuring flexible retry strategies to be configured differently for two different subscription periods.

Recommended General Revenue Recovery settings

When setting up a Smart retry policy for subscriptions, the recommended period is up to 1 month, to avoid overlapping periods on monthly subscriptions.

Additionally set the Subscription Status to "Mark the subscription as unpaid" and Invoice status to "Mark the invoice as uncollectible"

Overlapping period

If you set 2 months for the retries policy, overlapping periods may occur and affect the processing behavior of the subscription renewal and access.

Automations

If you wish to configure different retry strategies for Monthly vs Annual subscription types navigate to Automations.

Then set name and trigger, and in the conditions choose Subscription interval is, and set it to Yearly. Should you wish to treat Monthly subscriptions differently, repeat the setup for Monthly.

In the second step select or create the desired retry policy relevant for the subscription type and set the Subscription status and Invoice status as follows:

Then "Add action" to "Mark subscription unpaid", followed by another action to "Mark invoice uncollectable", then click Publish. Your final setup should appear as follows:

Non-Stripe Payment providers and Dual Retry run

Please note in case you are migrating from 3rd party provider to Stripe, and Dual Retry run is recommended, do not configure Automations, only use the general Revenue recovery as described above: Set the Subscription cancelation strategy to "Mark subscription unpaid" and Invoice status to "Mark invoice uncollectible" to ensure fallback retry logic in Piano can attempt retrying the legacy tokens for the optimal success on any migrated card retries.

For BYOP subscription retries, Passive Churn in Piano continues to be used. Any Smart Retry configurations will not affect subscription fail and retry logic managed by Piano.

Invoice Settings

Invoice event configuration

Invoice events are key validation and integration points for Piano and Stripe Billing. It is required that you configure the "Upcoming renewal events" to 3 days before.

Invoice finalization grace period configuration

Invoice finalization settings:

• Go To Settings (SETTINGS > BILLING > INVOICES)

• Select Billing in the Product setting section

• Go to Invoices, Scroll down to Invoice finalization period

• Check if your rule is configured to 1 hour, in case there is no rule, add a rule

• This determines the length of time between invoice being first created and when the invoice becomes finalized and sent to the user. It is required that this setting is set to 1 hour as per default.

• There should not be any other rules for invoice finalization grace period configured.

Disable invoice emails (if using non-Stripe payment provider)

To prevent customers from paying directly on Stripe, disable automatic notifications if you process payments on a third-party processor through BYOP. Navigate to Settings > Billing > Subscriptions and emails > Manage invoices sent to customers to disable automatic emails: Disable "Send finalized invoices and credit notes to customers".

If you are using Stripe Payments you have the option to leave this setting enabled.

Manage invoices sent to customers settings (if using non-Stripe Payment provider)

Under Settings → Billing → Subscriptions and emails. These settings apply to BYOP invoices since they use collection_method = send_invoice. Default Stripe values are recommended for both Subscription and Invoice statuses.

Stripe Reporting

Available Stripe Reports for Piano Clients

To learn about the Stripe reports, please refer to https://docs.stripe.com/stripe-reports.

Dashboard Financial Reports

Balance Summary Report

Piano Data Present: All Piano transactions converted to Stripe PaymentIntents and invoices

Metadata Included: Piano transaction IDs, application context, user identifiers

Use Case: Reconcile Stripe balance with Piano transaction history

Revenue by Customer Report

Piano Data Present: Piano users mapped to Stripe customers with Piano metadata

Customer Mapping: Piano User ID, application context

Use Case: Track revenue across Piano user base with Piano context preserved

Revenue by Product Report

Piano Data Present: Piano Resources mapped to Stripe Products

Product Metadata: Piano Resource IDs, titles

Use Case: Analyze revenue across Piano Resources/products with native Piano categorization

Billing-Specific Reports

Subscription Analytics Report

Piano Data Present: Piano subscriptions mapped to Stripe subscription schedules

Subscription Context: Piano Term information, subscription metadata, lifecycle data

Metrics Available: Customer lifetime value calculated on Piano subscription data

Note: Stripe supports free trials only, because of that Piano map both free and paid trials as phases of a schedule, therefore trial counts will not be populated in the Stripe’s report. This may change in the future with paid trials being more natively supported in Billing and available via API.

Subscription Churn Report

Piano Integration: Maps Stripe churn events back to Piano Subscription Insights

Data Flow: Stripe Revenue Recovery events → Piano churn reporting

Monthly Recurring Revenue (MRR) Report

Piano Data: Piano Terms converted to Stripe price_data with full pricing context

Revenue Attribution: MRR calculated from Piano pricing engine outputs

Segmentation: By Piano application, resource type, and term configurations

Invoice Status Report

Piano Context: Piano payment status mapping to Stripe invoice lifecycle

Status Synchronization: Sync between Piano payment states and Stripe invoice status

Revenue Recognition Reports

Income Statement

Piano Revenue: Piano subscription revenue recognized through Stripe billing cycles

Revenue Attribution: Maintains Piano application and resource-level revenue categorization

Period Recognition: Aligns with Piano subscription term periods and renewals via Subscription schedules and phases

Revenue Recovery Reporting

Clients using Stripe for Payments and Billing will also benefit from Revenue Recovery features and its associated reporting.

Churn Reporting in Piano Subscription Insights

Will continue to be available based off the webhook event handling and subsequent conversion event generation in Piano.

Stripe Billing Revenue Recovery events are mapped to Piano and will be available in the Subscription Insights and Piano Churn reporting.

Webhook handling

Here is how Stripe Billing Events are integrated into Piano, so that you can understand how critical subscription actions take place between the Stripe and Piano systems.

Stripe Billing Events

Piano Changes Overview

Piano Webhook Changes

Access webhook will have a small change to grace period length for Stripe managed subscriptions using Stripe Payments, because of the difference in grace period and retry behavior for Smart Retries compared with Piano Passive Churn management, as follows:

There are three fields available in access webhooks that relate to grace period - is_in_grace, grace_period_start_date, grace_period_length.

• In is_in_grace we send true if Piano subscription is in grace (i.e. smart retried in Stripe)

• In grace_period_start_date we send current period start date.

• In grace_period_length we will send the current billing period length (e.g. 1 month) for any Stripe retried subscriptions, as opposed to configured grace period length in Passive Churn or in the Term settings.

Dashboard changes

Clients using Piano will notice no changes to their day-to-day operations in the dashboard. The main expected change will happen for clients using Stripe Payments as they will no longer use Piano Passive churn, and the configuration will happen in Stripe Billing/ Revenue Recovery or Automations - enabling clients to configure their Smart Retries. No Passive Churn settings will take any effect on subscriptions made by Stripe Payments from the moment clients are switched to Stripe Billing. Additional information about Billing owner was added to the Subscription Details view to enable seeing which subscription is managed by Stripe.

Asynchronous payment method retry changes

Smart Retries significantly improve asynchronous payment method processing by enabling failed payment retries for direct debit: Clients using Stripe SEPA, BACS or ACH will enjoy improved failed renewal handling. Piano extends access management and enables Smart Retries to run on these methods driving additional revenue recovery, compared to the current approach when a subscription is immediately cancelled once the direct debit payment fails.

This improvement will introduce several changes related to async payment method processing, access management, conversion status, and payment status for these methods. For more information, please refer to the async retry flows above.

Email notifications changes

All notifications will remain working as they are even after clients have switched to Billing. The only change will occur to Renewal Notification failure where a few changes will happen due to Smart Retry logic. The grace period duration parameter will no longer be provided, as Smart Retries are not preset as a static cadence and instead act on many signals across the network and user behavior, dictating attempts at the most opportunistic time rather than on a preset schedule.

Email TO_CONSUMER_SUBSCRIPTION_AUTO_RENEWED_FAILURE is sent when renewal retry fails, and the grace period either starts or continues.

The above paragraph about grace period will be automatically hidden from the email for any switched subscriptions.

Grace period information in the Subscription details and History events (Dashboard and My Account)

Given that preset grace period isn’t available with Smart retries, the information about grace will be provided as follows: "Subscription to RESOURCE has entered a grace period"

Reporting Changes

Stripe configured retry policy length and number of retries will not be available in the Piano reports, as they are not available to Piano programmatically; the grace period will equal billing period.

API Changes

No general API changes, unless specified below. Any Piano API actions are mapped and transferred to Stripe as necessary within the scope of the currently supported feature set.

• API endpoint: POST /publisher/term/change/do

Change: A successful API response (200 OK) confirms the plan change only. Payment is processed asynchronously. A grace period is possible even after a 200 OK response.

Upgrade Changes

Comparison across all upgrade flows and payment types:

General Considerations

Support SLAs

What are the uptime and service level guarantees?

Piano continues to provide SLAs as contracted with each client. Stripe is one of the providers Piano uses to deliver services, and Piano is responsible for the overall service level of the platform — including the integration with Stripe and any other payment providers. Piano actively monitors the health of all integrations to ensure contracted service levels are met.

Support SLA/Model

Problem Ticket First Response Times

Standard Piano Problem response times based on the ticket Severity Level:

Problem Ticket Severity Levels

"Severity" is the assessed possible risk or effect of a problem with the Services.

Severity 1

1. The Services are causing the availability of the Client website or applications to be significantly affected;

2. There is a complete outage of a critical service or a recurring temporary outage of a critical service;

3. There is a security breach that exposes the personally identifiable information of Client customers; or

Severity 2

1. Due to a problem with the Services, users are not able to properly purchase access for, or gain access to, Client content;

2. The Services administrative applications (e.g. reporting, authoring, etc.) are unavailable;

3. There is an error, bug, or issue with the experience of a subset of Client customers (e.g. transactional emails are not being delivered properly / some but not all Client customers are viewing unintended media, content, or messages); or

Severity 3

1. Client is experiencing operational inconvenience caused by the Services;

2. Client needs or expects different functionality or presentation of information than Piano currently provides;

3. An individual user has reported a problem that has not been evidenced to be prevalent among Client customers.

Piano to Stripe subscription mapping

It is important to understand the difference between Stripe native Product catalog entities and Piano API level integration with Stripe Billing. Stripe provides more flexibility and functionality only via APIs which are used to map and integrate Piano term and subscription specifics. As per the mapping table provided above, you will notice that Piano term context is mapped to multiple entities instead of being represented as 1:1 term to price, therefore no Stripe catalog native price IDs are created or used, instead priceIDs are set via API which Stripe interface shows as "archived". This is expected system behavior on API level integrations.

Piano Metadata in Stripe

When Piano connects your subscriptions and payments to Stripe Billing, it automatically adds metadata to Stripe objects. This metadata links each Stripe record back to its corresponding Piano entity — your application, subscriber, subscription, or resource — so you can trace any Stripe object to its Piano source. Filtering of webhook events based on relevant Piano metadata is implemented to ensure non-Piano related events are ignored.

This documents every metadata field Piano sets in your Stripe account, what it represents, and the values you will see. Metadata is read-only: do not modify these fields directly in Stripe.

Stripe objects covered:

• subscription_schedule

• subscription

• invoice

• tax_rate

• payment_intent

• customer

• product

payment_method and price objects do not carry Piano metadata.

Field naming

All Piano metadata fields use camelCase and begin with the prefix "piano" — for example, pianoAid, pianoUid, pianoSubscriptionId. A small set of fields on payment_intent use an older naming style without the prefix; these are listed in the payment_intent section.

subscription_schedule

Piano creates a Stripe subscription schedule for each managed subscription. Metadata is stored at the phase level, not at the schedule root. The root-level subscription_schedule.metadata is always empty; all fields are set on subscription_schedule.phases[n].metadata.

Fields that do not change between phases are only written on the first phase — Stripe carries them forward automatically. Fields that stop applying to a period are explicitly cleared so they are not inherited.

subscription

subscription.metadata reflects the currently active phase of the subscription schedule and is kept in sync by Piano as phases change. When no schedule exists — after the schedule completes — the metadata retains the values from the last active phase.

The fields are identical to those on subscription schedule phases. The key difference is how they behave over time:

• Fixed fields (pianoCreationReason, pianoOrigin, pianoAid, pianoUid, pianoSubscriptionId) are set once and do not change over the subscription's lifetime.

• State fields (pianoInTrial, pianoPromoCodeId, pianoPromotionId, pianoPayMoreApplied, pianoInitialCustomPeriod, pianoNextBillingDateManuallyUpdated, pianoSubscriptionManuallyPrebilled, pianoVoucherId, pianoSubscriptionUpgraded) reflect the current period — present when that condition is active, absent otherwise.

• pianoAutoRenewalEnabled reflects the subscriber's current auto-renewal setting.

The following subscription locations are always empty: subscription.items[n].metadata, subscription.items[n].plan.metadata, subscription.items[n].price.metadata, subscription.plan.metadata.

invoice

Piano creates or enriches Stripe invoices in several contexts: the first invoice when a subscription is connected to Stripe Billing, renewal invoices (automatic and manual), upgrade invoices, one-time payment invoices, and gift invoices. All carry a common set of core fields; additional fields appear where applicable.

The table below covers invoice.metadata. See the note at the end of this section for the behavior of other invoice locations (lines, subscription_details, etc.).

Other invoice locations

tax_rate

Piano automatically creates tax rate objects in Stripe based on your Piano tax configuration. One metadata field is set on each tax rate object.

Do not modify tax rates created by Piano directly in the Stripe Dashboard.

payment_intent

Piano sets metadata on payment intents it creates — for subscription purchases, renewals, one-time payments, and gift purchases. Payment intents created automatically by Stripe for subscription renewals carry no metadata.

payment_intent.charges[n].metadata automatically mirrors payment_intent.metadata. No separate configuration is needed.

customer

Piano maps each subscriber to a Stripe customer record. One metadata field is set on customer creation and does not change.

product

Piano creates a Stripe product object for each Piano resource associated with a subscription or one-time payment.

payment_method and price

payment_method.metadata and price.metadata are always empty for all Piano-managed objects. No metadata is set on these entity types.

Stripe Unsupported features in Piano

In this phase following products or features are not yet available and integrated with Piano:

• Stripe Tax (Piano tax support is integrated as Stripe Manual rates at this stage)

• Invoicing (Standalone Invoicing product from Stripe not currently integrated, which is different from Invoice generation in Billing)

• Usage-based Billing and Product catalog created entities directly in Stripe

• Quotes

• Other features not explicitly documented as supported in this documentation.

Piano unsupported features in Subscription Piano powered by Stripe

These features are not yet available to use on “switched” subscriptions and will be released soon.

Coming soon

• Manual renewal in Checkout

Not supported in the current integration scope

• Dynamic terms all functionality

• Future start date

• Recurring Gifts (Private Preview)

Billing Integration agnostic features

These features are not in scope of the Stripe Billing integration or are irrelevant as they continue to be managed in Piano.

• Registration term

• External service (EVTs, and other 3^rd party integrations)

• Custom terms

• Access granted

• Linked Terms

• Site Licensing

Minimum charge amounts

Stripe applies minimum charge amounts, which may affect very small invoice amounts that might not be charged to the end-user. Here's how it works:

If an invoice amount due is less than the minimum chargeable amount for the currency, Stripe automatically marks the invoice as paid. The amount is debited from the customer's credit balance rather than processing a card payment. If there's no credit balance, the customer effectively gets that amount for free

The minimum chargeable amounts vary by currency. For example:

USD: $0.50

EUR: €0.50

GBP: £0.30

When this happens:

• The invoice status changes to paid automatically

• No payment attempt is made against the customer's payment method

• The small amount is recorded as paid (either from credit balance or effectively waived)

This commonly occurs with:

• Prorated amounts from subscription changes

• Very small subscription costs

• Tax-only invoices with minimal amounts

• Remaining balances after partial payments

This behavior helps avoid processing fees on very small transactions that might not be economical to charge.

Rounding rules for tax

Stripe rounding rules:

• Stripe rounds to the smallest currency unit (e.g., cents for USD, yen for JPY)

• When rounding decimal amounts, Stripe uses "half to even" rounding (also known as banker's rounding):

  • Values less than x.5 round down

  • Values greater than x.5 round up

  • For exactly x.5, Stripe rounds to the nearest even number

• For currencies without decimal places (zero-decimal currencies like JPY), no rounding is necessary as these currencies are already represented in their smallest unit.

Tax providers integrated in Piano use multiple rounding rules. Depending on your configuration, if one of the Avalara integrations is used, the rounding rules may be configured differently from the rules imposed by Stripe rounding rules.

Due to the rounding rules, in case the rules of tax service don’t match Stripe rules, the tax amount and total amount of invoice could be different from the amounts of the payment made in Piano checkout or Subscribe User. This discrepancy may occur for exclusive tax amounts only and not be more than 0.01 in the smallest currency unit.

Subscription renewal date handling for subscription switching

• Anchoring is a feature that allows you to return to the same calendar date back at renewals.

• Example: monthly subscription purchased on Jan 31.

  • With anchoring to 31^st of month: renewed on Feb 28, Mar 31, Apr 30, May 31

  • Without anchoring: renewed on Feb 28, Mar 28, Apr 28, May 28

• Anchoring is important for monthly and yearly billing periods (because of leap years). Any other billing periods (weekly, several days) aren’t affected by anchoring.

• For new purchases with Stripe Billing, Piano anchors to the moment of purchase.

• For existing subscriptions switched to Stripe Billing, Piano anchors to the next renewal date (the 1^st charge in Stripe).

• The anchor date is reset when a subscription enters a new billing period, for example after a trial or promotion to a full price billing period.

• In case the subscription does not have a monthly/yearly trial period, anchor is set once it enters any monthly/yearly period.

• Anchor timestamp is passed to Stripe as is. Stripe calculates calendar date anchor based on UTC time zone.

Renewal process date handling in Stripe

• Piano passes the renewal date in UTC to Stripe

• In the majority of cases billing cycle anchor is used to set the first renewal date for all switched subscriptions from which Stripe Billing renews the subscription.

• Stripe Billing honors the end of the month for the subscription renewal

Subscription Billing intervals

Please note, Stripe is currently allowing billing intervals to be set up to 3 years as maximum at the Price object. Therefore, any subscriptions with billing interval set to more than 3 years cannot be currently switched or purchased once switched to Stripe Billing.

• Same limitation affects the manual changes to Next Billing Date (NBD) on active subscriptions, and the NBD cannot be set to a future date longer than date +3 years.

For more details, see Billing periods and the 3-year guideline.

Validations

• Validations are done at:

  • Invoice preview (upon creation of subscription and any associated schedules)

  • Invoice draft upon renewal (validating amount and tax rates)

Data mapping from Stripe to Piano

Piano subscription object

Piano payment object

Legacy Subscription Switching to Stripe Billing

Switching existing subscriptions to Billing

For date and time handling for initial phase creation vs renewal date and time, Stripe uses the Epoch timestamp for absolute time creation.

All existing (legacy billing) Piano subscriptions which conform to supported features will be switched to Stripe Billing. Clients and their apps are scheduled to be switched in cohorts based on their use of Piano features and further planning by the operation and switching team.

Switching upgraded subscriptions to Stripe Billing

Clients using Upgrades and Downgrades can now be switched to Stripe Billing. Subscriptions that have been previously upgraded can be automatically switched to Stripe Billing as they conclude upgrading or downgrading.

All upgraded subscriptions that meet our general eligibility rules can be moved to Stripe Billing just like any other existing subscription.

Subscriptions that still have an upgrade scheduled but not yet completed are not switched to Stripe Billing until that upgrade is completed or cancelled.

In practice, this means:

• If a subscription was created earlier as part of an upgrade (even months ago and already renewed), it can now be moved to Stripe Billing once it is eligible.

• If a subscription has an upgrade scheduled but not completed (or suspended but not fully cancelled), it will be held back from switching until the upgrade flow is resolved.

Upgrades with Stripe Billing

All channels now behave like On-site Upgrades, Stripe processes payment off-session after the plan change is applied.

On-site Upgrades

No behavioral change. On-site Upgrades with Stripe Billing work the same as in legacy Piano billing: payment is off-session, and a failed payment puts the subscription in grace period. Clients using upgrade offers via on-site will see behavior consistent with all other channels.

Upgrade Types and Timing

Immediate Upgrade

The subscription changes at the moment of the upgrade request. Stripe generates an invoice for the prorated amount — the unused portion of the current plan applied toward the new plan — and attempts payment off-session.

Proration formula:

Deferred (Scheduled) Upgrade

The subscription changes at end of billing period. No proration. Full price of new plan billed from the next renewal date. Optionally: subscriber can gain access to new resource immediately, before billing transition.

Deferred upgrades are not affected by the off-session model change — they were already off-session in legacy billing. No change in payment behavior. The additional benefit in processing asynchronous payment methods with Stripe Billing, in case of payment failure instead of immediate cancellation grace period and Smart retries apply for all supported methods.

BYOP Async methods and Upgrades

For BYOP async payment methods, the payment is initiated after the upgrade but confirmed or rejected days later (typically 2–5 days depending on the payment method). If that deferred payment fails:

Why BYOP async cancels immediately

BYOP async payments (such as direct debit or bank transfer) are processed on Piano's side, not Stripe's. Piano payment processing rules apply. In legacy Piano billing, BYOP async upgrade payment failures resulted in immediate cancellation — no grace period. This behavior remains the same. If your publisher account uses BYOP async payment methods and supports upgrades, subscribers will be cancelled rather than put into grace period if their async upgrade payment fails.It is recommended to use Stripe Payments for async payment method processing which can be retried.

Upgrade Lifecycle Operations

For deferred upgrades, publishers can manage the lifecycle with the following operations:

FAQ

Q: What happens when Piano cannot connect or create a valid subscription in Stripe Billing?

• • Piano has a retry mechanism in case of network error and continue to try to create the subscription entities in Billing up to 5 times, in case of failover, subscription cannot be created, or in case of incomplete creation such subscription will be cancelled in Stripe and recreated again after problem has been fixed.

  • NOTE: in case you decide to set up email notifications in Stripe Billing, this will trigger sending a subscription cancelation notification. It is recommended to use Piano notifications, as in such case Piano will not be sending such notifications, until a problem is resolved.

Q: How does Piano ensure subscriptions are properly and accurately created in Stripe Billing?

• • Piano integration uses several validation approaches to ensure consistency and accuracy. All subscriptions created are validated after creation using Invoice preview feature, to match amount, currency, date, billing period.

  • Any subscription renewals are also validated to ensure accurate tax rate, pricing, promotions, or any other lifecycle adjustments or updates are accurately sync’d between Piano and Stripe using the Draft Invoice generated upon renewal by Stripe which provides 72 hours window for validation.

Q: Why are there two transactions appearing on the transaction list in the Stripe Dashboard for any newly created subscriptions?

• • Any new subscriptions created in Stripe Billing as a result of purchase in the Checkout or Subscribe User will show two transactions in the Stripe dashboard, one in ‘Cancelled’ state and one in ‘Succeeded’.

    

  • This is an expected behavior and a result of using Stripe API operations during subscription creation. At this time Stripe is not able to remove this record appearing in the dashboard, and Piano is not able to make this change. This duplicated record listing is purely visual and has no impact on any subscription processing or billing. The correct payment is associated with the newly created subscription invoice. Subscribers will only see a single transaction in the Piano Dashboard and on their credit card or bank statement.

Q: What actions NOT to perform on a subscription in Stripe dashboard?

• • Generally, it is not recommended to make any changes to Subscriptions and Invoices as well as any associated entities in Billing / Product catalog. Any changes will lead to subscription becoming out-of-sync and require to be manually reset in Piano or will need full management outside Piano.

  • Viewing reports, managing access and account settings are supported

  • Any payments related configurations e.g. Radar are allowed and supported

  • Working with data in Stripe with 3^rd party apps/plugins and other Stripe products which does not affect Catalog entities and its states is also not limited.

Q: Why do I see different tax amounts in the Subscription view versus Invoice view?

• • In case the subscription had modifications made during purchase (e.g. Promotion applied), you will see the Subscription general amount and period in the Subscription view in Stripe which typically shows upcoming amount and period only.

  • The initial period tax amount is accurately represented in the Invoice view. This is to avoid rounding rule discrepancies on the initial period or purchase amount, prior to Stripe Billing applying the tax calculation natively.

Q: What are Revenue recovery settings and where do I find them?

• • Revenue recovery settings control how Stripe handles failed subscription payments. The most important option is Smart Retries, which automatically re-attempts a failed charge using Stripe's machine-learning model to pick the best retry timing.

  • Location in Stripe: Settings → Billing → Revenue recovery

  • Smart Retries is enabled by default. Stripe will retry failed charges up to 8 times over a 2-week period.

  • Keep Smart Retries enabled with the default configuration. This is the most important of the five settings and the default is fully compatible with Piano.

Q: What could go wrong if Revenue recovery is configured differently?

• • If Smart Retries is disabled, no retry logic runs and failed payments are lost. If a third-party retry tool is also active, double charges are possible. Both scenarios must be resolved before your Switch.

  • Two situations to flag before Switching:

    • Smart Retries are disabled — a client may have turned this off because they use a dedicated revenue recovery or dunning tool (e.g. Churnkey, Recurly Recover, a custom dunning flow). In this case, confirm which retry logic should take precedence and disable the other. Let your Piano contact know.

    • A custom retry schedule is active instead of Smart Retries — the overlap can trigger multiple charge attempts for the same invoice, leading to double charges and customer complaints.

Q: What is the Invoice finalization period setting and where do I find it?

• • The invoice finalization period is the window between when Stripe generates a subscription renewal invoice and when it attempts to charge the customer. During this window, Piano can validate the invoice — confirming amounts, applying any last-minute adjustments, and ensuring Piano and Stripe are synchronized before payment is collected.

  • Location in Stripe: Settings → Billing → Subscriptions and emails → Invoice finalization period. The invoice finalization period is set to 1 hour by default.

  • Do not change this setting. The 1-hour default is the recommended configuration for Piano. This window is a critical integration point — Piano uses it to run pre-charge validations.

Q: What could go wrong if Invoice finalization is configured differently?

• • Any additional rules configured in this section may conflict with Piano's integration validation logic. Flag any customizations here with your Piano contact before your Switch.

  • Reducing the finalization period leaves less time for Piano's pre-charge checks to complete, which can result in charges being collected before Piano has confirmed the invoice is correct. Extending it delays renewals and may affect billing cycle expectations for subscribers.

Q: What is the Upcoming invoice events setting and where do I find it?

• • This setting controls when Stripe fires an upcoming invoice webhook event before a subscription renewal. Piano uses this event to run a pre-renewal sync check — confirming that the subscription state, pricing, and subscriber details are consistent between Piano and Stripe before the invoice is finalized.

  • Location in Stripe: Settings → Billing → Subscriptions and emails → Prevent failed events → Upcoming renewal events

  • Stripe defaults to sending the upcoming invoice event 7 days before renewal. Set this to 3 days before renewal. The default value is acceptable. The critical point is that this event must be configured — leaving it unset disables the pre-renewal sync entirely.

Q: What could go wrong if Upcoming invoice events are configured differently?

• • If upcoming invoice events are not configured, Piano cannot run its pre-renewal validation. Operations performed close to a renewal — such as plan changes, coupon application, or subscription updates on either the Piano or Stripe side — may not be reflected in the renewal invoice, resulting in an out-of-sync state.

  • An out-of-sync state means the amount Stripe charges may not match what Piano expects. This can affect revenue reporting, subscription state, and subscriber experience.

Q: What is the Invoice level rounding setting and where do I find it?

• • This setting controls how Stripe rounds tax amounts on invoices. There are two options: round at the invoice level (a single rounding operation applied to the total tax) or round at the item level (rounding applied to each line item individually before summing).

  • Location in Stripe: Settings → Billing → Invoices → Manual tax amount rounding

  • Stripe defaults to rounding at the invoice level. Keep the default. Round at the invoice level. Do not change this setting.

Q: What could go wrong if Invoice rounding is configured differently?

• • Changing to item-level rounding introduces small rounding discrepancies between Stripe's calculated tax totals and the pre-created tax rates Piano uses. Even minor discrepancies — fractions of a cent — can trigger out-of-sync states between Piano and Stripe and cause reconciliation failures.

  • This is a low-visibility setting that is easy to overlook, but its effect on tax reconciliation is significant. Confirm it is set to invoice-level rounding before your Switch.

Q: What is the Automatic invoice emails setting and where do I find it?

• • This setting controls whether Stripe automatically sends invoice and payment-related emails directly to subscribers. When enabled, Stripe sends finalized invoices and, optionally, payment reminders from its own email system, independently of any emails Piano or the client's platform may also send.

  • Location in Stripe: Settings → Billing → Subscriptions and emails → Manage invoices sent to customers

  • Stripe enables two options by default:

    • Send finalized invoices and credit notes to customers — enabled

    • Send reminders if a recurring invoice has not been paid — disabled

  • The default past-due behavior (for both invoice past-due scenarios) is: leave the subscription past-due after 60 days.

  • Disable automatic invoice emails. This is the recommended configuration for Piano clients.

  • The Stripe default (emails enabled) is not recommended because Piano also manages subscriber communications. Leaving Stripe emails enabled results in subscribers receiving duplicate emails — one from Stripe and one from Piano or the client's platform.

Q: Are there cases where keeping Stripe emails enabled is acceptable?

• • Yes, in one specific scenario: if the client does not use non-Stripe payment providers and does not use Stripe payment links, keeping Stripe's invoice emails enabled is acceptable — provided the client is aware and has decided this is their preferred experience.

Q: What is BYOP and do I need it?

• • A: BYOP (Bring Your Own Processor) is for clients who use a non-Stripe payment processor such as Braintree or Datatrans or Stripe unsupported methods e.g. Zlick. If you currently use Stripe Payments, you do not need BYOP — your setup works natively. If you use a different processor, in order to switch to Stripe Billing for subscription management while keeping your existing processor for charge collection, BYOP is required.

Q: Can I have both Stripe-native and BYOP subscribers in the same application?

• • A: Yes. Piano supports a mixed fleet — some subscribers can be on Stripe-native payment methods while others are on BYOP. Each subscription's renewal logic is handled according to its payment method type. You can also switch individual subscribers between Stripe and BYOP as needed, although this feature is pending release mid-April.

Q: Do I need to disable Stripe invoice emails for BYOP?

• • A: Yes — this is required for BYOP. Because Stripe generates a real invoice for every renewal cycle, if invoice emails are enabled, your subscribers will receive a Stripe invoice with a payment link. Since your processor collects the charge out-of-band, that payment link would be non-functional and confusing. Disable "Send finalized invoices and credit notes to customers" in Stripe Billing settings.

Q: Our system treats a successful upgrade API response as confirmation that payment was collected. What do we need to change?

• • A: You need to decouple payment confirmation from the upgrade response. A 200 OK from POST /publisher/term/change/do now means the plan change was applied in Stripe successfully — not that payment was collected. To confirm payment, poll the subscription state via GET after the upgrade call. Alternatively, implement webhook handling for invoice.paid (payment succeeded for sync methods and invoice.finalized for asynchronous payment methods), and invoice.payment_failed (payment failed, grace period started).

Q: Does the subscriber's Stripe subscription ID change when they upgrade?

• • A: No. The same Stripe subscription ID is maintained throughout the subscriber's lifecycle regardless of how many plan changes occur.

Q: A subscriber upgrades, payment fails, and the grace period expires. What plan are they on?

• • A: The subscription is cancelled. It is not reverted to the pre-upgrade plan. If the subscriber wishes to continue, they would need to start a new subscription.

Q: Some of our subscribers use direct debit (BYOP async). What happens if their upgrade payment fails?

• • A: BYOP async payments do not have a grace period on upgrade failure. If the deferred payment fails after an upgrade, the subscription is cancelled immediately — the same behavior as in legacy Piano billing. Stripe Smart Retries do not apply to BYOP payments. Access is granted at the moment of upgrade, but cancelled if the async payment fails.

Q: What happens to a subscriber's 3DS confirmation step when they upgrade?

• • A: There is no 3DS step during the upgrade. Payment is off-session using the payment method on file with Stripe. If 3DS is required for the off-session charge, Stripe handles this through its standard retry and authentication request flow.

Q: Are bulk upgrades via Action Manager affected?

• • A: No. Bulk upgrades via Action Manager are always deferred (end of billing period) and were already off-session. No behavioral change.

Q: How do Immediate upgrades behave when Stripe Billing manages a subscription in grace and retry state?

• • A: Currently, such Upgrades are allowed for subscription paid by synchronous payment methods only, asynchronous payment methods do not allow upgrading while there is a pending payment nor support grace and retry. In case, an immediate upgrade is made on a subscription in a grace period paid by synchronous payment method, such upgrade is supported, although the original retrying invoice will not be automatically voided, in case of eventual success it may lead to charge. In case subscription upgrade payment fails, because the initial subscription is already in grace and retry, the subscription will be cancelled. Additional enhancements are under evaluation.

How do Piano and Stripe work together?

Q: Who is responsible for what in Piano?

• A: Piano and Stripe share responsibility with clear boundaries. Piano manages your subscriptions, business rules, and customer experience. Stripe handles billing and — when used as your payment provider — payment processing and financial infrastructure. Piano owns the integration across all systems.

Q: What is Piano responsible for?

• A: Piano is responsible for:

  • Subscription management — creating, upgrading, renewing, and cancelling subscriptions

  • Access control — granting and revoking user access based on subscription status

  • Checkout — the purchase experience, offer presentation, and conversion flow

  • Promotions and pricing — calculating discounts, applying promotional terms, determining what price is charged

  • Grace periods — managing how long access continues while a payment is being retried

  • Upgrade logic — handling plan changes, proration, and scheduling

  • BYOP connector – processing payments on existing Piano payment provider integrations

Q: What is Stripe responsible for?

• A: Stripe is responsible for:

  • Recurring invoicing — generating invoices on each billing cycle via Stripe Billing

  • Payment processing — collecting payments, managing payment methods, handling 3DS authentication (when using Stripe Payments)

  • Payment retries — automatically retrying failed payments using Stripe Smart Retries (when using Stripe Payments)

  • PCI compliance — securing all card and payment data (when using Stripe Payments)

  • Financial reporting — revenue data, payment reconciliation, and reporting via Stripe Dashboard

  Note: Payment processing, retries, 3DS, and PCI compliance apply when using Stripe as your payment provider. If you use your own payment provider (BYOP), these responsibilities remain with your provider. See the BYOP section below for details.

  In short: Piano manages your subscriptions, business rules, and customer experience. Stripe handles billing and — when used as your payment provider — payment processing and financial infrastructure. Piano owns the integration across all systems.
  

Q: What happens when something goes wrong?

• A: Piano is your first point of contact for all issues. Our support team triages whether the issue is in Piano's subscription layer or Stripe's payment infrastructure and handles resolution end-to-end.

  Issue	Who resolves it
  User lost access unexpectedly	Piano
  Upgrade didn't apply correctly	Piano
  Invoice amount looks wrong	Piano
  Payment failures or processing issues	Stripe or 3rd party PSP (Piano as escalation point)
  3DS authentication issue	Stripe or 3rd party PSP (Piano as escalation point)
  Piano generated objects and/or data in Stripe Dashboard look unexpected	Piano
  Smart retries aren't working	Stripe (Piano as escalation point)

  Piano is accountable for the full subscription-to-payment flow, including the integration between the two systems.

Q: Is our payment data secure?

• A: Yes. Piano maintains its own PCI compliance as documented in our existing security documentation. When using Stripe Payments, card data goes directly to Stripe — a PCI Level 1 certified processor — via their client-side SDKs. Piano handles subscription information (what plan, what price, what access) but does not store card numbers, CVVs, or raw payment credentials in the Piano integration flow.

Can I use my own payment provider (BYOP)?

Q: Can we keep our existing payment processor with Piano?

• A: Yes. Piano supports a Bring Your Own Processor (BYOP) model. In this setup, Stripe handles subscription scheduling and invoicing, while your existing payment provider (e.g., Datatrans, Adyen, Worldpay) continues to process the actual payments.

  How it works:
  

  1. When a renewal is due, Stripe generates and finalizes an invoice

  2. Piano grants subscription access immediately

  3. Piano routes the payment to your payment provider for collection

  4. On successful payment, the invoice is reconciled

  5. If payment fails, the subscription enters a grace period managed by Piano Passive Churn

  Your existing payment provider continues to handle payment collection. Stripe provides the scheduling and invoicing engine. Piano orchestrates everything.

Q: Do we have to eventually move to Stripe for payments?

• A: BYOP is a supported operating mode. You can continue using your existing payment provider as is.That said, using Stripe for both billing and payments offers advantages: automated Smart Retries, native 3DS handling, unified financial reporting in Stripe Dashboard, and consistent grace period behavior across all subscription operations. If you're already evaluating your payment provider setup, this may be a natural moment to consider adopting Stripe Payments.

Q: Can we switch between our provider and Stripe after going live?

• A: Yes. You can switch payment methods between your provider and Stripe in both directions, and this can be done on a per-subscription basis. This gives you the flexibility to run a hybrid setup — for example, migrating payment processing to Stripe gradually, or keeping specific payment types on your existing provider while moving others to Stripe.

How does Piano handle Stripe customer credit balances?

Q: What is a Stripe customer credit balance?

• A: A stored amount on a Stripe Customer that Stripe automatically applies to reduce the next invoice. Left unmanaged, this would silently lower the charged amount below the subscription price.

Q: How does Piano handle it during a purchase or Switch?

• A: Piano temporarily removes the credit balance before creating the subscription invoice, then restores it immediately after finalization. This ensures the invoice is locked at the correct subscription amount before the balance is returned.

  The sequence is: remove balance → create draft → finalize → restore balance → attach payment intent.

  The balance is removed for seconds only. Piano does not wait for invoice.paid to restore it.

Q: Does this affect renewal invoices?

• A: No. Piano does not intervene in Stripe-generated renewal invoices. If a customer has a credit balance at renewal time, Stripe will apply it and the renewal charge may be lower than the full subscription price.

Auto-renewal and retries during grace periods

Q: A subscriber turned off auto-renewal, but we still charged them. Is this a bug?

• A: No. If the subscription was in a grace period at the time auto-renewal was turned off, retries were still running against an open invoice. If a retry succeeded, the charge is expected behavior — the cancellation is deferred to period end, not applied immediately. If the subscriber did not want the charge, issue a refund.

Q: Why isn't the cancellation immediate when auto-renewal is turned off in a grace period?

• A: To preserve the subscriber's access and keep the retention flow intact. A subscriber in a grace period who turns off auto-renewal may still reconsider — for example, by updating their payment method through My Account — before the period ends. Voiding the invoice immediately would eliminate that recovery path. The deferred model keeps it open.

Q: Does this affect BYOP subscriptions the same way as Stripe-native payment methods?

• A: Yes, the cancellation behavior is identical — deferred to end of billing period, retries continue, a charge may still succeed. The only difference is the retry engine: Stripe Smart Retries for Stripe-native methods, Piano's own retry loop for BYOP.

Q: Will a renewal webhook fire if the retry succeeds after auto-renewal was turned off?

• A: Yes. If a retry succeeds during the grace period, a standard renewal event and webhook will fire. The subscription is then marked to cancel at the next period boundary. Be aware of this when building downstream reporting or fulfillment integrations that key off renewal events.

Last updated: July 03, 2026