Part 3: Manage Subscriptions with Stripe Billing — Stripe Payments

Subscription Operations

All your familiar Piano subscription management features continue to work. This article provides a general overview of Stripe Billing subscription management for Stripe Payments clients. For a complete breakdown, see the Stripe Billing Integration technical reference.

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. Note that due to risk protection, only up to 3-year billing periods are supported by Stripe, so 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

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

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 is required.

• Eligible methods only: When you or a subscriber change the payment method on a subscription, only the methods eligible for that subscription's customer and currency are offered. If a previously saved method is no longer eligible, the subscriber is 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.

Payment method availability after the switch: Currency is not the only reason a subscriber's payment methods can be spread across several Stripe customers. Before the switch, each Stripe payment provider configuration in your app (for example Stripe, Stripe Elements, and Stripe Apple Pay) created its own Stripe customer, each with its own payment methods.

After the switch, every subscription is anchored to one Stripe customer, and only methods attached to that customer can be selected for it or set as its default. The wallet in My Account and in the publisher dashboard lists every method saved for the subscriber, including methods that belong to another customer, so a method that is visible there can still fail to apply. If a card appears in the wallet but cannot be set as default, it almost certainly belongs to a different customer.

What to do? Ask the subscriber to add the card again from the subscription they want it to pay for. Piano attaches the new method to that subscription's anchored customer. You can then delete the older entry so the wallet only lists methods the subscriber can use. We are reviewing whether to filter out methods that a subscription cannot use, so this guidance may change.

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; the 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 Piano billing, where immediate upgrades made via MyAccount, Dashboard and API resulted in a rollback (no charge, no change). On-site Upgrades are the exception: they 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, and 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 and payment-to-dynamic: Upgrades between payment term subscriptions, and from a payment term to a dynamic term, are supported. See Dynamic Terms for how these map to Stripe subscription schedules. 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

This section shows where your Piano data appears in the Stripe Dashboard, and which of it you must never edit there.

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

This section lists the Stripe reports available to you, and how they sit alongside the reporting you already have in Piano.

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, a 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, and remaining balances after partial payments.

Troubleshooting

This section covers the situations clients most often ask about after the Switch, and what to do in each one.

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

This is expected behavior for new purchases. See the note under Transactions Tab in Understanding Your Data in Stripe above.

Out-of-Sync Subscriptions

Manual changes to Piano-managed entities in Stripe put the subscription out of sync.

Piano automatically cross-checks and repairs discrepancies it detects during its own validations. Changes Piano cannot cross-check, for example a product or price created directly in Stripe and attached to a subscription, cannot be repaired automatically. In those cases Piano stops managing billing and collection for that subscription, every operation except cancellation is blocked in the Piano Dashboard, and Piano keeps extending access to the original resource only while the subscription is active in Stripe.

A notification appears in the Subscription details view when this happens. Contact Piano support: support can reset the subscription state so that Piano manages it again. Fully automated reconciliation is planned for a future release.

Getting Help

Documentation

• Stripe Billing Documentation

• Stripe Dashboard Guide

• Stripe Revenue Recovery

Support

• Contact your Piano Account Manager

• Submit support tickets through Piano Dashboard

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

Last updated: September 07, 2026