QuickStart Guide

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.

The order of setup

1. Your Piano representative enables the Stripe Billing integration on your application.

2. You create or connect your Stripe account in the Piano Dashboard, and confirm that both the Connected Account ID and the API credentials are present and valid.

3. You apply the Stripe Dashboard settings below.

4. Piano reviews your configuration with you before the Switch.

5. New purchases move to Stripe Billing as soon as your application is activated. Existing subscriptions move at their next renewal.

Steps 2 and 3 are yours. Steps 1 and 4 are coordinated with your Piano team.

Existing Stripe Payments clients

If your Stripe account is already connected to Piano for Payments, it is connected to Piano's Stripe Billing Connect account automatically. Check that your Stripe API keys are configured in the Payment Provider settings and add them if they are not. Nothing else is needed in Piano. Go to the Stripe Dashboard configuration 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, under Edit Business → Billing Provider), 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

You still need a Stripe account for Billing, even though your payments are collected by your own processor. Contact your Piano representative to enable the Stripe Billing integration, then follow Part 2 of the Client Guide Series for BYOP, which covers only the settings that apply to you.

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.

Billing Settings

Revenue recovery, retries (Only Stripe Payments clients)

In the Stripe Dashboard, go to Billing → Revenue recovery → Retries → Cards. Direct link: dashboard.stripe.com/revenue_recovery/retries.

Recommended configuration:

• Retry period: 2 weeks (to avoid overlapping periods on monthly subscriptions). Stripe lets you choose 1 week, 2 weeks, 3 weeks, 1 month, or 2 months, and set the number of attempts. Stripe's own recommended setting is 8 attempts within 2 weeks.

• 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 grace period

In the Stripe Dashboard, navigate to Settings → Billing → Invoices → Invoice finalization grace period and locate the Edit button next to the default rule. Direct link: dashboard.stripe.com/settings/billing/invoice.

Required setting:

• Set the 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. Piano uses this window to validate the invoice before payment is collected.

Upcoming renewal events

In the Stripe Dashboard, navigate to Settings → Billing → Subscriptions and emails → Prevent failed payments → 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.

Stripe's dashboard default on a new account is 7 days, which is compatible. It does, however, widen the period within which changes may still happen before the renewal invoice is finalized. On an existing Stripe account, check that the setting is configured at all: if it is off, the pre-renewal sync does not run and subscriptions can go out of sync.

Manual tax amount 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.

This setting applies only to invoices with manual tax rates, which is what Piano creates. Invoices calculated with automatic Stripe Tax always sum tax amounts first and then round, which is one more reason Stripe Tax must not be enabled while Piano manages tax.

Disable Automatic Invoice Emails

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.

BYOP clients: this is required. It prevents customers from paying directly on Stripe when your own processor is collecting the charge. Also make sure no payment links are enabled on invoices, otherwise there may be double charges.

Stripe Payments clients: this is optional. You may leave the setting enabled if you prefer Stripe to send invoice emails. If you do, make sure Stripe email rules and Piano Email Manager do not conflict or send duplicate emails.

Manage Failed Payments setting

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

This section applies to both Stripe Payments and BYOP clients.

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 the Invoice Status to Uncollectible.

These settings apply to BYOP invoices, because BYOP invoices use collection_method = send_invoice and Stripe's automatic dunning does not apply to them. Stripe Payments subscriptions use charge_automatically and are governed by the Manage failed payments section instead, so a pure Stripe Payments client does not need to set the statuses here.

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.

Pre-switch configuration checklist

Work through this with your Piano team before the Switch.

In Piano

In the Stripe Dashboard, all clients

In the Stripe Dashboard, Stripe Payments clients only

In the Stripe Dashboard, BYOP clients only

Last updated: August 26, 2026