FAQ

FAQ

Piano Connection to Stripe Billing

Q: What happens when Piano cannot connect or create a valid subscription in Stripe Billing?

• A: Piano has a retry mechanism in case of network error and continues to try to create the subscription entities in Billing up to 5 times. In case of failover, if a subscription cannot be created, or in case of incomplete creation, such a subscription will be cancelled in Stripe and recreated again after the problem has been fixed.

Subscription Accuracy and Validation

Q: How does Piano ensure subscriptions are properly and accurately created in Stripe Billing?

• A: Piano integration uses several validation approaches to ensure consistency and accuracy. All subscriptions created are validated after creation using the Invoice preview feature, to match amount, currency, date, and billing period.

• Any subscription renewals are also validated to ensure accurate tax rate, pricing, promotions, or any other lifecycle adjustments or updates are accurately synced between Piano and Stripe using the Draft Invoice generated upon renewal by Stripe, which provides a 72-hour window for validation.

Stripe Dashboard Transactions

Q: Why are there two transactions appearing on the transaction list in the Stripe Dashboard for any newly created subscriptions?

• A: Any new subscriptions created in Stripe Billing as a result of a purchase in the Checkout or Subscribe User will show two transactions in the Stripe dashboard: one in 'Cancelled' state and one in 'Succeeded'.

• This is an expected behavior and a result of using Stripe API operations during subscription creation. At this time, Stripe is not able to remove this record appearing in the dashboard, and Piano is not able to make this change. This duplicated record listing is purely visual and has no impact on any subscription processing or billing. The correct payment is associated with the newly created subscription invoice. Subscribers will only see a single transaction in the Piano Dashboard and on their credit card or bank statement.

Actions Not to Perform in Stripe Dashboard

Q: What actions NOT to perform on a subscription in Stripe dashboard?

• A: Generally, it is not recommended to make any changes to Subscriptions and Invoices as well as any associated entities in Billing / Product catalog. Any changes will lead to a subscription becoming out-of-sync and require to be manually reset in Piano or will need full management outside Piano.

• Viewing reports, managing access, and account settings are supported.

• Any payments related configurations, e.g., Radar, are allowed and supported.

• Working with data in Stripe with 3_rd party apps/plugins and other Stripe products which do not affect Catalog entities and its states is also not limited.

Tax Amounts in Subscription vs. Invoice View

Q: Why do I see different tax amounts in the Subscription view versus Invoice view?

• A: In case the subscription had modifications made during purchase (e.g., Promotion applied), you will see the Subscription general amount and period in the Subscription view in Stripe which typically shows upcoming amount and period only.

• The initial period tax amount is accurately represented in the Invoice view. This is to avoid rounding rule discrepancies on the initial period or purchase amount, prior to Stripe Billing applying the tax calculation natively.

Revenue Recovery Settings

Q: What are Revenue recovery settings and where do I find them?

• A: Revenue recovery settings control how Stripe handles failed subscription payments. The most important option is Smart Retries, which automatically re-attempts a failed charge using Stripe's machine-learning model to pick the best retry timing.

• Location in Stripe: Billing → Revenue recovery → Retries (direct link: https://dashboard.stripe.com/revenue_recovery/retries)

• Stripe's recommended setting is 8 attempts within 2 weeks.

• Keep Smart Retries enabled with the recommended configuration. This is the most important of the five settings and the recommended setting is fully compatible with Piano.

Q: What could go wrong if Revenue recovery is configured differently?

• A: If Smart Retries is disabled, no retry logic runs and failed payments are lost. If a third-party retry tool is also active, double charges are possible. Both scenarios must be resolved before your Switch.

• Two situations to flag before Switching: Smart Retries are disabled: a client may have turned this off because they use a dedicated revenue recovery or dunning tool (e.g., Churnkey, Recurly Recover, a custom dunning flow); confirm which retry logic should take precedence and disable the other. A custom retry schedule is active instead of Smart Retries: the overlap can trigger multiple charge attempts for the same invoice, leading to double charges and customer complaints.

Invoice Finalization Period Setting

Q: What is the Invoice finalization period setting and where do I find it?

• A: The invoice finalization period is the window between when Stripe generates a subscription renewal invoice and when it attempts to charge the customer. During this window, Piano can validate the invoice, confirming amounts, applying any last-minute adjustments, and ensuring Piano and Stripe are synchronized before payment is collected.

• Location in Stripe: Settings → Billing → Invoices, where Stripe labels the setting Invoice finalization grace period (direct link: https://dashboard.stripe.com/settings/billing/invoice). The invoice finalization period is set to 1 hour by default.

• Do not change this setting. The 1-hour default is the recommended configuration for Piano. This window is a critical integration point. Piano uses it to run pre-charge validations.

Upcoming Invoice Events Setting

Q: What is the Upcoming invoice events setting and where do I find it?

• A: This setting controls when Stripe fires an upcoming invoice webhook event before a subscription renewal. Piano uses this event to run a pre-renewal sync check, confirming that the subscription state, pricing, and subscriber details are consistent between Piano and Stripe before the invoice is finalized.

• Location in Stripe: Settings → Billing → Subscriptions and emails → Prevent failed events → Upcoming renewal events

• Stripe defaults to sending the upcoming invoice event 7 days before renewal. Set this to 3 days before renewal. The default value is acceptable. The critical point is that this event must be configured. Leaving it unset disables the pre-renewal sync entirely.

Invoice Level Rounding Setting

Q: What is the Invoice level rounding setting and where do I find it?

• A: This setting controls how Stripe rounds tax amounts on invoices. There are two options: round at the invoice level (a single rounding operation applied to the total tax) or round at the item level (rounding applied to each line item individually before summing).

• Location in Stripe: Settings → Billing → Invoices → Manual tax amount rounding. Stripe defaults to rounding at the invoice level. Round at the invoice level. Do not change this setting.

Automatic Invoice Emails Setting

Q: What is the Automatic invoice emails setting and where do I find it?

• A: This setting controls whether Stripe automatically sends invoice and payment-related emails directly to subscribers. Location in Stripe: Settings → Billing → Subscriptions and emails → Manage invoices sent to customers. Disable automatic invoice emails. The Stripe default (emails enabled) is not recommended because Piano also manages subscriber communications, which would result in duplicate emails.

Q: Are there cases where keeping Stripe emails enabled is acceptable?

• A: Yes, in one specific scenario: if the client does not use non-Stripe payment providers and does not use Stripe payment links, keeping Stripe's invoice emails enabled is acceptable, provided the client is aware and has decided this is their preferred experience.

BYOP (Bring Your Own Processor)

Q: What is BYOP and do I need it?

• A: BYOP (Bring Your Own Processor) is for clients who use a non-Stripe payment processor such as Braintree or Datatrans or Stripe unsupported methods e.g. Zlick. If you currently use Stripe Payments, you do not need BYOP. Your setup works natively. If you use a different processor, in order to switch to Stripe Billing for subscription management while keeping your existing processor for charge collection, BYOP is required.

Q: Can I have both Stripe-native and BYOP subscribers in the same application?

• A: Yes. Piano supports a mixed fleet: some subscribers can be on Stripe-native payment methods while others are on BYOP. Each subscription's renewal logic is handled according to its payment method type. You can also switch individual subscribers between Stripe and BYOP as needed.

Q: Do I need to disable Stripe invoice emails for BYOP?

• A: Yes. This is required for BYOP. Because Stripe generates a real invoice for every renewal cycle, if invoice emails are enabled, your subscribers will receive a Stripe invoice with a payment link. Since your processor collects the charge out-of-band, that payment link would be non-functional and confusing. Disable "Send finalized invoices and credit notes to customers" in Stripe Billing settings.

Upgrade Behavior

Q: Our system treats a successful upgrade API response as confirmation that payment was collected. What do we need to change?

• A: You need to decouple payment confirmation from the upgrade response. A 200 OK from POST /publisher/term/change/do now means the plan change was applied in Stripe successfully, not that payment was collected. To confirm payment, poll the subscription state via GET after the upgrade call, or implement webhook handling for invoice.paid (payment succeeded for sync methods and invoice.finalized for asynchronous payment methods) and invoice.payment_failed (payment failed, grace period started).

Q: Does the subscriber's Stripe subscription ID change when they upgrade?

• A: No. The same Stripe subscription ID is maintained throughout the subscriber's lifecycle regardless of how many plan changes occur.

Q: A subscriber upgrades, payment fails, and the grace period expires. What plan are they on?

• A: The subscription is cancelled. It is not reverted to the pre-upgrade plan. If the subscriber wishes to continue, they would need to start a new subscription.

Q: Some of our subscribers use direct debit (BYOP async). What happens if their upgrade payment fails?

• A: BYOP async payments do not have a grace period on upgrade failure. If the deferred payment fails after an upgrade, the subscription is cancelled immediately, the same behavior as in Piano billing. Stripe Smart Retries do not apply to BYOP payments.

Q: What happens to a subscriber's 3DS confirmation step when they upgrade?

• A: There is no 3DS step during the upgrade. Payment is off-session using the payment method on file with Stripe. If 3DS is required for the off-session charge, Stripe handles this through its standard retry and authentication request flow.

Q: Are bulk upgrades via Action Manager affected?

• A: No. Bulk upgrades via Action Manager are always deferred (end of billing period) and were already off-session. No behavioral change.

How do Piano and Stripe work together?

Q: Who is responsible for what?

• A: Piano and Stripe share responsibility with clear boundaries. Piano manages your subscriptions, business rules, and customer experience (subscription management, access control, checkout, promotions and pricing, grace periods, upgrade logic, and the BYOP connector). Stripe handles billing and, when used as your payment provider, payment processing and financial infrastructure (recurring invoicing, payment processing, payment retries via Smart Retries, PCI compliance, and financial reporting). Piano owns the integration across all systems.

Q: What happens when something goes wrong?

• A: Piano is your first point of contact for all issues. Our support team triages whether the issue is in Piano's subscription layer or Stripe's payment infrastructure and handles resolution end-to-end.

Q: Is our payment data secure?

• A: Yes. Piano maintains its own PCI compliance as documented in our existing security documentation. When using Stripe Payments, card data goes directly to Stripe, a PCI Level 1 certified processor, via their client-side SDKs. Piano handles subscription information (what plan, what price, what access) but does not store card numbers, CVVs, or raw payment credentials in the Piano integration flow.

Can I use my own payment provider (BYOP)?

Q: Can we keep our existing payment processor with Piano?

• A: Yes. Piano supports a Bring Your Own Processor (BYOP) model. In this setup, Stripe handles subscription scheduling and invoicing, while your existing payment provider (e.g., Braintree, Datatrans, Cybersource, GoCardless) continues to process the actual payments. When a renewal is due, Stripe generates and finalizes an invoice, Piano grants subscription access immediately, Piano routes the payment to your payment provider for collection, and on successful payment the invoice is reconciled. If payment fails, the subscription enters a grace period managed by Passive Churn Prevention.

Q: Can we switch between our provider and Stripe after going live?

• A: Yes. You can switch payment methods between your provider and Stripe in both directions, and this can be done on a per-subscription basis. This gives you the flexibility to run a hybrid setup.

How does Piano handle Stripe customer credit balances?

Q: What is a Stripe customer credit balance and how does Piano handle it?

• A: A stored amount on a Stripe Customer that Stripe automatically applies to reduce the next invoice. During a purchase or Switch, Piano temporarily removes the credit balance before creating the subscription invoice, then restores it immediately after finalization (remove balance → create draft → finalize → restore balance → attach payment intent). The balance is removed for seconds only. Piano does not intervene in Stripe-generated renewal invoices. If a customer has a credit balance at renewal time, Stripe will apply it and the renewal charge may be lower than the full subscription price.

Auto-renewal and retries during grace periods

Q: A subscriber turned off auto-renewal, but we still charged them. Is this a bug?

• A: No. If the subscription was in a grace period at the time auto-renewal was turned off, retries were still running against an open invoice. If a retry succeeded, the charge is expected behavior. The cancellation is deferred to period end, not applied immediately. If the subscriber did not want the charge, issue a refund. This behavior is identical for BYOP subscriptions; the only difference is the retry engine (Stripe Smart Retries for Stripe-native methods, Piano's own retry loop for BYOP).

Dynamic terms

Q: How do dynamic terms appear in Stripe, and do they work with BYOP?

• A: Dynamic term subscriptions appear as subscription schedules in your Stripe Dashboard. Each access period maps to a phase in the schedule; phase-level metadata (such as pianoInTrial) tracks which phase is active. Payment-to-dynamic upgrades are supported and follow the same subscription-first model. Dynamic terms are fully supported for BYOP subscriptions: invoice.finalized triggers the Piano subscription renewal, and your processor handles the charge out-of-band. If a dynamic term has access periods longer than 3 years, the term is skipped during switching (it stays on Piano billing); your other terms on the same app still switch normally.

Last updated: August 26, 2026