Part 3: Manage Subscriptions with Stripe Billing — BYOP

Subscription Operations

All your familiar Piano subscription management features continue to work. This article provides a general overview of Stripe Billing subscription management for BYOP clients. For a complete breakdown, see the Stripe Billing Integration technical reference and the Non-Stripe Providers (BYOP) section.

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.

Canceling Subscriptions: Cancellation without refund takes immediate effect; cancellation with refund processes the refund first, then completes cancellation.

Manual Renewal: The core Manual renewal flow in MyAccount and Dashboard is supported for BYOP payment methods, covering both pre-billing renewal and grace-period escape scenarios.

Payment Method Changes: Subscribers can switch their payment method between a non-Stripe (BYOP) provider and Stripe. See the payment method management table on Subscription Operations for details. A subscriber can switch to a Stripe-native payment method at any time to opt in to Smart Retries.

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 the configured retry schedule.

• Success: invoice marked paid, subscription continues. Retries exhausted: the Stripe subscription is cancelled and the Piano subscription is expired.

Grace period length is set per term under Manage → Terms, in the term's settings. If Passive Churn Prevention is enabled, it overrides the term-level values with its own default of 15 days. To keep custom lengths, create churn prevention logics under Management → Churn Prevention and select them at term level.

Your grace period settings continue to apply to BYOP subscriptions, because Piano still runs the retries. For Stripe-native subscriptions they are ignored: Stripe determines the retry schedule, and the grace period equals the billing period.

Subscription Upgrades & Downgrades (BYOP)

Piano uses Stripe's subscription-first model for all upgrades: the plan change is applied immediately and payment is collected afterwards. For BYOP subscriptions, the key difference from Stripe-native is what happens on payment failure.

Supported upgrade types (same as Stripe-native, with the failure behavior above):

• Immediate upgrade with or without proration

• Deferred (end-of-billing-cycle) upgrade, optionally with early access to the new resource

• Payment-to-payment and payment-to-dynamic upgrades, same currency only.

• Suspend / resume / admin cancellation of pending upgrades

• All channels: My Account, Dashboard, API, on-site

When a subscriber upgrades, access to the new plan is granted immediately and the subscription ID remains the same. No new subscription is created.

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 payment activity. For BYOP, charges are collected through your PSP and recorded against Stripe invoices marked as out-of-band.

Customers Tab: Piano users mapped to Stripe customers

Subscriptions Tab: All active Piano subscriptions. View current and upcoming invoices and billing schedules.

Product Catalog Tab: Piano Resources converted to Stripe Products, including Piano metadata. 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. You may occasionally see rounding differences of $0.01 (or equivalent) on excluded tax amounts.

Reporting

Stripe billing reports (Subscription Analytics, Churn, MRR, Invoice Status) and financial reports (Balance Summary, Revenue by Customer/Product) are available. For BYOP, invoices appear in Stripe marked as out-of-band since the charge is collected through your PSP.

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 ✓

• Disable automatic Stripe invoice emails and confirm no payment links are enabled on invoices 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 set the Stripe Subscription status to "Cancel" for BYOP (use "Unpaid")

• Never modify Product Catalog items or Piano-created tax rates directly 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)

• Don't make 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 BYOP 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

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

Support

• Contact your Piano Account Manager

• Submit support tickets through Piano Dashboard

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

Last updated: August 26, 2026