Piano Stripe Billing Integration Guide - Manage Subscriptions

Subscription Operations

All your familiar Piano subscription management features continue to work.

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

Supported Operations

• Update payment methods

• Toggle auto-renewal on/off

• Change next billing date

• Cancel subscriptions immediately

• Process refunds (full and partial)

• Upgrades and Downgrades

• Manual renewal in Dashboard and My Account

Important Notes

Changing Next Billing Date:

When you change a subscriber's next billing date, Piano creates a complimentary period between now and the new date. In the Stripe Dashboard, you may temporarily see a $0 price until the new billing date arrives. This is expected behavior. Also, note due to risk protection only up to 3-year billing periods are supported by Stripe, therefore you cannot set a next bill date beyond 3 years currently.

Canceling Subscriptions:

• Cancellation without refund: immediate effect

• Cancellation with refund: refund processes first, then cancellation completes

Payment Method Updates: Non-Stripe payment methods (BYOP) are now supported — see the Non-Stripe Providers section for more details.

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.

Upgrade Operations for BYOP Subscriptions : For BYOP subscriptions, the upgrade plan change is applied immediately and payment is collected afterwards. The key difference from Stripe-native is what happens on payment failure:

Multi-currency and Multi-customer Support :

Stripe maintains a separate customer record per currency. Piano automatically detects and resolves multi-currency and multi-customer configurations during migration — no manual setup required.

• Eligible methods only: Subscribers will only see payment methods eligible for their subscription's customer and currency. If a previously saved method is no longer eligible, the subscriber will be prompted to add a new one.

• Currency-aware payment method capture: When adding a new Stripe payment method, subscribers select their currency. Piano ensures the method is attached to the correct Stripe customer automatically.

• Ongoing protection at checkout: Piano's automated fixing tasks progressively align each subscriber to one Stripe customer per currency.

Non-Stripe Providers (BYOP)

Piano's Stripe Billing integration supports publishers who process payments through non-Stripe processors — including Braintree, Datatrans, and other PSPs. Existing and new subscriptions using these payment methods can be switched to Stripe Billing.

BYOP (Bring Your Own Processor) refers to subscriptions where payment is collected through a third-party PSP — such as Braintree or Datatrans — rather than through Stripe's native payment infrastructure. In BYOP mode:

• Stripe manages the subscription schedule, invoice lifecycle, and billing records.

• Piano processes the actual payment charge through your configured PSP.

• All transactions are recorded in Stripe as invoices, maintaining a complete and auditable billing history.

This approach — sometimes called "out-of-band" billing — is Stripe's canonical pattern for publishers who want Stripe Billing's infrastructure while retaining their existing payment processor relationships.

BYOP renewal flow

When a BYOP subscription renews, the following sequence occurs:

BYOP vs. Stripe-native: key differences

Subscription switching

BYOP support enables switching to Stripe Billing for all subscription types, even when the subscriber's payment method is non-Stripe:

• Existing active subscriptions (via the bulk migration process)

• Newly purchased subscriptions at the point of checkout

• One-time payments (one-offs)

• Gift subscriptions

Grace period and retry handling for BYOP

• Failed renewal payment: subscription enters grace period (duration configurable per publisher).

• Subscriber access maintained during grace period.

• Piano retries payment via your PSP on configured retry schedule.

• Success: invoice marked paid, subscription continues. Exhausted: subscription cancelled.

Subscription Upgrades & Downgrades

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.

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.

When a subscriber upgrades to a higher tier, access to the new plan is granted immediately. Payment for the upgrade is collected in a separate step after the subscription is updated. If payment fails, the subscription enters a grace period and the subscriber is directed to update their payment method via their account page. The subscription ID remains the same throughout — no new subscription is created.

Supported Features Overview

Understanding Your Data in Stripe

Stripe Dashboard Navigation

Your Piano data appears in Stripe as follows:

Home Dashboard: Overview of transactions and subscription activity

Transactions Tab: Shows all payment attempts and completions

• Note: New subscriptions may show two transactions (one cancelled; one succeeded). This is expected behavior from Stripe's API and is purely visual. The correct payment is associated with your subscription invoice; this only applies to new purchases. Subscribers will only see a single transaction in the Piano Dashboard and on their credit card or bank statement.

Customers Tab: Piano users mapped to Stripe customers

Subscriptions Tab: All active Piano subscriptions

• View current and upcoming invoices

• See subscription details and billing schedules

Product Catalog Tab: Piano Resources converted to Stripe Products

• Includes Piano metadata (Resource titles, IDs)

• Do not modify products or tax rates directly in Stripe

Tax Rates

Piano automatically creates manual tax rates in Stripe based on your existing Management + Billing tax configuration. These rates are synchronized between systems and should not be modified in the Stripe Dashboard.

Automatic Stripe Tax is not supported in the current phase and must not be enabled as it will lead to conflicts.

Rounding Differences: Due to different rounding rules between Piano's tax providers and Stripe, you may occasionally see differences of $0.01 or equivalent in the smallest currency unit. This only affects excluded tax amounts.

Reporting

Available Stripe Reports

Financial Reports:

• Balance Summary Report

• Revenue by Customer Report

• Revenue by Product Report

Billing Reports:

• Subscription Analytics Report

• Subscription Churn Report

• Monthly Recurring Revenue (MRR) Report

• Invoice Status Report

• Revenue Recovery Report

Revenue Recognition Reports:

• Income Statement (requires Stripe Revenue Recognition - paid feature)

Piano Reports

Your existing Piano Subscription Insights and churn reporting continue to function, with Stripe billing events flowing back to Piano for comprehensive analytics.

Best Practices

Do's ✓

• Configure Revenue Recovery in Stripe Dashboard before going live

• Use Piano Dashboard for all subscription management operations

• Continue using Piano email notifications (recommended)

• Review Stripe reports alongside Piano analytics for complete visibility

Don'ts ✗

• Never modify Product Catalog items directly in Stripe Dashboard

• Never change tax rates created by Piano in Stripe

• Avoid making subscriber changes directly in Stripe (use Piano Dashboard)

• Don't configure multiple Stripe accounts for a single Piano application

• Don't enable Stripe Tax (not yet supported - use Piano tax configuration)

• Don't make any direct changes to subscriptions, invoices, or associated entities in Stripe as this will cause out-of-sync states

Minimum Charge Amounts

Stripe enforces minimum chargeable amounts by currency (e.g., $0.50 USD, €0.50 EUR, £0.30 GBP).

If an invoice amount falls below this minimum:

• Stripe automatically marks the invoice as paid

• The amount is deducted from customer credit balance if available

• Otherwise, the customer receives the amount free

This commonly occurs with:

• Prorated amounts from subscription changes

• Very small subscription costs

• Tax-only invoices

• Remaining balances after partial payments

Troubleshooting

Invoice Validation Errors

Piano validates all invoices before finalization. If validation fails:

1. Payment collection stops automatically

2. Access is extended (minimum 3 days to prevent disruption)

3. Piano support is alerted to investigate

4. Issue is resolved and invoice re-finalized

Two Transactions Appearing

For new subscriptions, you may see two transactions in Stripe - one cancelled and one succeeded. This is expected behavior from Stripe's API and is purely visual. The correct payment is associated with your subscription invoice; this only applies to new purchases.

Payment Method Changes

Changing a subscriber's payment method between Stripe and a non-Stripe provider is not yet available.

Out-of-Sync Subscriptions

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

If you use Stripe Billing to directly manipulate Piano-managed Product catalog, Subscriptions, or Invoices and Piano cannot cross-check entities, such subscriptions will become out-of-sync. For out-of-sync subscriptions:

• Piano will stop managing subscription billing and collection

• Subscription and transaction data will no longer be accurate in the Piano Dashboard

• Piano will keep extending access to the original subscription resource(s) while the subscription is active in Stripe

• You will see a notification in the Subscription details view

If an out-of-sync situation occurs unexpectedly, please contact the Piano support team immediately.

Getting Help

Documentation

• Stripe Billing Documentation

• Stripe Dashboard Guide

• Stripe Revenue Recovery

Support

For assistance with Piano's Stripe Billing integration:

• Contact your Piano Account Manager

• Submit support tickets through Piano Dashboard

• For Stripe-specific billing questions, consult your Stripe Account Manager

Last updated: July 02, 2026