Piano Stripe Billing Integration Guide - Setup

Getting Started

Enabling Stripe Billing

Stripe Billing must first be enabled on your application by your Piano representative. Clients are enabled progressively based on their use of Piano features. If you have any questions, please contact your Piano representative.

This article provides a general overview of the Stripe Billing setup. For a complete breakdown of all configuration steps, supported features, and detailed implementation instructions, learn more in Stripe Billing integration.

Step 1: Determine your setup

Existing Stripe Payments clients

If you are already using Stripe for Payments:

• Your existing Stripe account is automatically connected to Piano's Stripe Billing Connect account.

• No additional setup is required in Piano beyond adding your Stripe API keys (if not already configured).

• Simply log in to your Stripe Dashboard and complete the configuration steps outlined below.

New or non-Stripe Payments clients

If you are not currently using Stripe for Payments:

• You will need to create a Stripe account for Billing purposes.

• Contact your Piano representative to enable Stripe Billing for your application.

Step 2: Create or connect your Stripe account

Option A: Create a new Stripe account

1. In the Piano Dashboard, navigate to Edit Business → Billing Provider.

2. Click Add, then Connect.

3. Complete the Stripe onboarding flow.

Follow the instructions provided by Stripe to create your account.

Option B: Connect an existing Stripe account

If you already have a Stripe account:

1. In the Piano Dashboard, navigate to Edit Business → Billing Provider.

2. Click Add, then Connect to authenticate your account via Stripe onboarding.

Clients already using Stripe Payments have their accounts connected automatically and are already presented in the Billing configuration.

Ensure your Stripe API keys are configured in the Payment Provider settings. Piano uses the account ID from your Stripe payment provider configuration to ensure that your existing customers and payment methods are carried over to Billing.

Step 3: Verify configuration

Your Stripe Billing setup is complete when:

• A Connected Account ID is present.

• API credentials are added and valid.

Once both are configured, you can proceed to configure the settings in your Stripe dashboard as detailed in the section below.

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

This setting determines the time between invoice creation and when it's finalized and sent to subscribers.

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. Change the "Upcoming renewal events" setting to be triggered 3 days before a subscription renews. This is an important integration point between the systems. Keeping this at the default 7 days is compatible; however, extends the period within which changes may still happen before the renewal invoice is finalized.

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 Management + Billing can manage BYOP grace and retry logic and handle cancellation, in no case set the Subscription status to Cancel.

Switch Timeline

Your Piano team will coordinate your transition to Stripe Billing through a phased rollout process:

1. Pre-switch

Configuration review and Stripe account setup.

2. Piano Subscriptions for New Purchases

From the moment your application is activated on Stripe Billing, all new subscription purchases are processed through Stripe immediately. No action is required on your part — new subscribers are automatically placed on Stripe Billing from day one.

3. Switch for Existing Subscriptions

Switching your existing subscriptions is a brief, coordinated process. During the Switch, Piano creates all required subscription entities in Stripe Billing and sets each subscription to renew through Stripe from its next renewal date. From this point forward, Stripe becomes the owner of subscription billing and renewals.

There is no subscriber-visible change during this process and no interruption to access.

A small number of subscriptions may not transition automatically at renewal. This typically applies to subscriptions that are in a failed payment or suspended state at the time of renewal, or that require individual review. These subscriptions remain on the previous billing setup temporarily and are handled by Piano’s account team. They transition at the next successful renewal or payment method update.

No subscriber access is affected.

Any subscription that does not transition automatically will resolve at the next billing event — either the next renewal attempt or when the subscriber updates their payment method. No manual intervention is required by the publisher.

If you have questions about a specific subscription, contact the Piano support team.

4. Post-switch and Go-Live

Validation and monitoring period. All subscription purchases and renewals flow through the integrated Stripe Billing system.

Your Piano Account Manager will provide specific dates and migration steps for your account.

Appendix: Revenue Recovery Settings

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:

• Subscription Status: "Mark the subscription as unpaid"

• Invoice status: "Mark the invoice as uncollectible"

Overlapping Period Warning

If you set 2 months for the retries policy, overlapping periods may occur and affect the processing behavior of the subscription renewal and access. The notifications sent to the subscriber may also be confusing.

Automations

If you wish to configure different retry strategies for Monthly vs. Annual subscription types, navigate to Automations in the Stripe Dashboard.

1. Set name and trigger

2. In the conditions, choose "Subscription interval is" and set it to Yearly (or Monthly)

3. Select or create the desired retry policy for the subscription type

4. Set the Subscription status and Invoice status as described above

5. Add actions to "Mark subscription unpaid" and "Mark invoice uncollectible"

6. Click Publish

Appendix: Stripe Account Configuration

Account Hierarchy Scenarios

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.

Important Notes

• Once your Stripe account is connected to Piano and used for billing, you cannot change it. To switch to a different account, a migration on both Piano and Stripe side will be required

• The same connected account used across different Piano applications doesn't guarantee that billing configurations will be created for each application

• To disconnect already connected accounts from Piano, clients need to inform their Piano and Stripe Account representatives

Last updated: July 03, 2026