New subscriptions can now stay under Flopay's management from signup through each renewal. Merchants get one consistent lifecycle across Stripe and PayPal, including immediate starts, trials, future-dated starts, recurring charges, and day-to-day subscription controls.
Existing provider-managed subscriptions continue unchanged. This release applies only to new subscriptions admitted to the Flopay-managed path.
Start on the right schedule
When payment is due today, checkout and POST /v1/subscriptions charge the first cycle, activate the subscription, record the paid invoice, and schedule the next charge. Free trials and future starts create no upfront subscription invoice, while one-time items in the same cart are still charged normally. Paid introductory trials collect the trial fee now and schedule the standard recurring amount for the trial end.
The recurring price, currency, and cadence agreed at signup remain stable even if the catalog changes later. The existing gatewaySubscriptionId field remains populated; Flopay-managed subscriptions use an opaque flo_ identifier that must not be sent to Stripe or PayPal.
Renew across eligible payment methods
When a subscription is due, Flopay attempts the saved-payment cascade across eligible methods and gateways. A successful charge records the payment and paid invoice, advances the agreed schedule, and emits the established invoice, renewal, and purchase events.
If every eligible option is declined or unavailable, the subscription moves to past_due, the failed invoice is recorded, and invoice.payment_failed is emitted without advancing the billing date. Automated dunning is not included, so merchants should continue their existing failed-payment recovery workflow.
Keep lifecycle changes predictable
Existing subscription operations can cancel, pause, resume, reactivate, change, or extend Flopay-managed subscriptions without a separate provider subscription. Plan changes apply to future billing without repricing completed invoices or transactions.
A checkout keeps its selected ownership path through retries, 3DS returns, and later completion. Operators can confirm the active modes through GET /v1/health using globalNewSubscriptionMode, paypalVaultedEnabled, and paypalLegacyMode.
What's included
- Checkout API — Immediate, free-trial, future-dated, and paid introductory starts for new Flopay-managed subscriptions.
- Subscriptions — Automatic renewals plus consistent lifecycle controls across eligible Stripe and PayPal payment routes.
- SDK — Flopay SDK
1.6.0supports vaulted PayPal order and setup-token continuations for Flopay-managed checkout. - Webhooks — Existing subscription and invoice event envelopes retain their established shapes and meanings.
Developer notes
Upgrade to Flopay SDK 1.6.0 or later to use advertised paypal_vaulted continuations. Integrations that continue to send paymentMethodType: "paypal" retain provider-managed PayPal Subscription behavior. There are no removed APIs or existing-subscription migrations.
Why it matters
Merchants can operate one predictable subscription journey while Flopay chooses an eligible payment route for each charge. Customers keep the schedule and terms they accepted, and developers keep the API and webhook contracts they already use.