FloPay Backend Changelog

Client-facing updates for FloPay backend and API releases.

v1.7.23 - Single-client branding controls #

Authorized operators can now manage a merchant's customer-facing branding while each action remains scoped to one explicitly selected client.

26 Aug 2026

Feature

Branding

API

Authorized operators can now read, replace, or clear branding on behalf of one explicitly selected client. Existing client-managed branding behavior remains unchanged.

What changed

Operator-assisted branding management is restricted to one selected client for each action, with no implicit or cross-client fallback.
The same whole-replacement and idempotent clear behavior now applies whether branding is managed by the client or by an authorized operator.
The OpenAPI schemas for GET /v1/branding and PUT /v1/branding now describe nested SDK button styles and custom appearance rules more precisely.

Why it matters

Operators can help merchants maintain consistent branding across SDK embeds, hosted checkout, branded emails, and other white-label experiences without affecting another client's configuration.
Developers generating clients or forms from the OpenAPI specification receive more accurate branding types.

Developer notes

Existing branding payloads and client authentication continue to work without changes.
No SDK update, payload migration, or merchant action is required. This release contains no breaking changes or removed public APIs.

v1.7.22 - Card-storage disclosure on hosted forms #

Hosted payment and card-setup forms now explain secure card storage and link buyers to the Card Storage Policy without interrupting their progress.

25 Aug 2026

Improvement

Checkout

Accessibility

Buyers entering a new card now see a consistent notice directly below the payment or card-setup button explaining that their card is stored securely in a PCI DSS-compliant vault. The notice links to the Card Storage Policy so buyers can learn more before submitting their details.

What changed

Hosted payment and card-setup forms that collect a new card now display the card-storage disclosure automatically.
The Card Storage Policy opens in a new tab, preserving the in-progress form and any details already entered.
The notice adapts to the form theme and available screen width, and its link supports keyboard and screen-reader use.
Saved-card and non-card payment flows are unchanged because they do not display the new-card form.

Why it matters

Buyers receive clear, consistent information about card storage at the point where they enter their card details.
Merchants receive one centrally maintained disclosure across hosted card flows without adding or synchronizing their own copy.

Developer notes

The hosted form supplies the notice automatically, and it cannot be hidden or replaced. Do not render a duplicate card-storage notice around the form; review any custom copy already placed there.
No public API, SDK, or configuration changes are required. There are no breaking changes, migrations, or other operational actions for standard integrations.

v1.7.21 - Platform security and dependency refresh #

Flopay's backend dependencies have been refreshed, including a security update for API documentation support, while preserving existing integration behavior.

24 Aug 2026

Security

Maintenance

Reliability

Existing integrations continue to work unchanged after this platform maintenance release. Backend dependencies and development tooling have been refreshed without changing public product behavior.

What changed

Updated runtime dependencies and development tooling to their targeted compatible versions.
Addressed a reported dependency security advisory in the tooling that supports Flopay's API documentation.
Public APIs, request and response payloads, checkout flows, SDK contracts, and webhook delivery remain unchanged.

Why it matters

The refresh incorporates current upstream fixes while preserving compatibility for existing integrations.

Developer notes

No SDK update, payload change, merchant configuration, migration, or operational action is required.
This release contains no breaking changes or removed public APIs.

v1.7.20 - Subscription rebill filters for payments and webhooks #

Payment and webhook-event lists, exports, and batch resends can now use a linked subscription's successful rebill count.

24 Aug 2026

Feature

Payments

Webhooks

Subscriptions

API

Payment and webhook-delivery reporting can now organize records by the number of successful renewal charges recorded for each linked subscription. Merchants and operators can isolate activity for subscriptions that have not yet renewed, compare more established subscriptions, and target webhook redelivery without combining separate datasets.

What changed

GET /v1/payments, GET /v1/admin/payments, GET /v1/webhooks/events, and GET /v1/admin/webhooks/events now accept numeric subscription.rebillCount filters, such as subscription.rebillCount[gte]=2, using eq, gt, gte, lt, and lte operators.
Payment and webhook-event results can be ordered with sort[asc]=subscription.rebillCount or sort[desc]=subscription.rebillCount. Records without a linked subscription are placed last, and equal rebill counts retain stable pagination.
POST /v1/payments/exports, POST /v1/admin/payments/exports, POST /v1/webhooks/events/exports, and POST /v1/admin/webhooks/events/exports support the same filters and sorting, and can include subscription.rebillCount as an opt-in numeric field in CSV or JSON output.
POST /v1/webhooks/events/resend accepts the same rebill-count filters, allowing a batch resend to target webhook events linked to subscriptions within a selected renewal range.

Why it matters

Payment and webhook-delivery reports can segment activity by subscription maturity without matching records across separate exports.
Support and operations teams can focus webhook redelivery on a relevant subscription cohort while retaining the existing client-scoped resend behavior.

Developer notes

Add relation=subscription only when the nested subscription data is needed in a list response. Filtering or sorting by subscription.rebillCount does not expand the relation automatically.
The export field is opt-in and does not change the default payment or webhook-event export schema.
This change is additive. Existing response fields, pagination envelopes, default ordering, relation loading, webhook payloads, and automatic delivery behavior are unchanged; no SDK update, merchant configuration, or data migration is required.

v1.7.19 - Subscription recovery history #

Subscription recovery campaigns, retry rounds, and the next scheduled recovery retry are now visible through public read APIs and timeline projections.

24 Aug 2026

Feature

Subscriptions

API

Flo-managed subscription recovery is now easier to inspect from merchant dashboards, admin tools, and operational workflows. Teams can review the recovery campaigns and retry rounds attached to a subscription, and timelines now show the next scheduled recovery retry when one is already planned.

What changed

GET /v1/subscriptions/:id/recovery returns the authenticated client's recovery history for a subscription.
GET /v1/admin/subscriptions/:id/recovery?clientId= gives administrators the same recovery view for a selected client.
Timeline future events can now include subscription.recovery_retry for the next scheduled recovery retry, using the active recovery schedule instead of projecting an ordinary rebill while recovery is still in progress.
Recovery reads are paginated and client-scoped, so consumers can safely build dashboard and support views without fetching unbounded history.

Why it matters

Merchants and support teams can explain where a failed renewal is in recovery without inferring state from separate events.
Buyer-facing and operator-facing timelines no longer suggest a normal upcoming rebill when the subscription is actively waiting for a recovery retry.

Developer notes

This is an additive, read-only API change. Existing subscription, timeline, webhook, and SDK-facing behavior remains compatible.
Clients with strict timeline event validation should accept the new subscription.recovery_retry future event code.
The new recovery endpoints use the standard paginated list response shape: data, page, limit, pages, and total.

v1.7.18 - Safe client dunning policies #

Clients can narrow retry timing, attempt limits, and eligible decline categories for future Flo-managed campaigns without weakening lifecycle or platform safeguards.

23 Aug 2026

Feature

Subscriptions

API

Flo-managed subscription recovery now supports versioned client-specific dunning policies. Clients with unusual billing cycles or customer promises can narrow future retry behavior, while every client without an override keeps the documented platform defaults automatically.

What changed

GET /v1/settings/dunning-policy returns the authenticated client's complete effective policy and protected platform limits. Its limit metadata distinguishes the released interval-scaled platform default from the 60-day cap enforced after PATCH activates an override; DELETE reverts future campaigns to platform defaults.
Policies can narrow retry windows and scheduled attempts by cadence, restrict eligible normalized decline reasons, and move retries to permitted HH:mm UTC times.
Every new campaign freezes the effective policy identity, revision, constraints, retry offsets, and cutoff. Changing a policy never rewrites an active campaign; responses make this visible as future_campaigns_only.

Safety guarantees

Overrides cannot exceed the default cadence limits, eight attempts, 60 days, or the exact next billing boundary.
Clients without an override retain the released interval-count-scaled default cadence, including multi-year schedules whose final retry can be later than 60 days but is always before the exact next billing boundary.
Provider-terminal and operationally uncertain outcomes retain their existing handling. A client cannot make a non-retryable outcome retryable or bypass reconciliation.
Paid-through dates advance only after confirmed payment, and required failure and expiry lifecycle events are still emitted when a client policy ends recovery.
Policy reads and writes are scoped to the authenticated client. Invalid settings are rejected without changing the active revision or disabling the default recovery path.

Developer notes

This is an additive authenticated API. Existing SDK-facing routes, payloads, defaults, status codes, and event contracts are unchanged.
Use the returned policyId, revision, effectiveAt, and activeCampaignChanges fields for operator visibility. Campaign reporting can use the corresponding frozen policy snapshot to interpret later recovery results.
null clears a cadence control, eligible-category, or retry-time override back to its platform default. Omitted fields keep the previous active revision's value.

v1.7.17 - Measured dunning retry timing #

Flo-managed subscription retries can now use client-local recovery evidence while retaining the approved default schedule whenever evidence is weak or unsafe.

22 Aug 2026

Feature

Reporting

Analytics

Subscriptions

API

Flo-managed subscription dunning can now time new retry campaigns from measured approval signals. The optimizer uses only the merchant's own recent recovery history and automatically keeps the approved default schedule when evidence is insufficient, stale, conflicting, unavailable, or no longer shows meaningful improvement.

What changed

New retryable campaigns evaluate normalized decline reason, subscription cadence, UTC hour, UTC day/payday window, and an available privacy-safe issuer pattern against the preceding 90 days of client-local completed retries.
Timing is adjusted only when both candidate and baseline have at least 100 observations and the measured recovery lift is at least 5 absolute percentage points. Competing timings within 2 percentage points fall back to default.
Every campaign freezes its baseline and selected offsets, decision evidence, and fallback reason. Active campaigns never move when new evidence arrives, and all retries remain ordered and before the next billing boundary.
Subscription stats now include dunningTimingPerformance, comparing baseline and optimized campaigns by retry attempts, successful recoveries, recovered revenue, and average time to recovery.

Why it matters

Merchants can recover failed renewals at times supported by their own measured approval patterns without weakening dunning safety or creating cross-client data leakage.
The built-in baseline makes improvements measurable and reversible: low or inconclusive lift withdraws the optimized timing for future campaigns while preserving the default policy.
Reporting shows whether optimized timing improves recovery with fewer attempts and less time to settlement.

Developer notes

This is an additive response change. Existing routes, request parameters, authentication, lifecycle behavior, idempotency rules, and previously returned subscription-stat fields are unchanged.
Consumers with strict response validation should accept the always-present dunningTimingPerformance object.
Timing cohorts use campaign billing_cycle_at for the requested half-open period and include only campaigns that reached a business retry round (round_number >= 1). No customer-, card-, or issuer-level rows are returned.
Evidence acquisition is advisory. If the evidence query is unavailable, campaign creation continues with the full default schedule and records evidence_unavailable in the frozen policy snapshot.

v1.7.16 - Dunning recovery revenue reporting #

Subscription analytics now show the count and gross revenue recovered by Flo-managed retry rounds alongside existing rebill totals.

22 Aug 2026

Feature

Reporting

Analytics

Subscriptions

API

Subscription analytics now distinguish successful renewals recovered by Flo-managed dunning from ordinary rebills. Merchants can see both how many renewals were recovered and the gross recurring revenue they represent, using the same reporting period and currency rules as the existing subscription stats.

What changed

GET /v1/subscriptions/stats and GET /v1/admin/subscriptions/stats now include an always-present dunningRecovery object with:
- recoveredRebillCount — the number of successful rebills recovered by Flo-managed retry rounds.
- recoveredRebillRevenue — the recovered gross amount and its three-character currency code.
Recovery is a strict subset of the existing rebillCount and rebillRevenue totals. Ordinary first-attempt successes, provider-managed retries, unrelated payments, and unsuccessful recovery campaigns are excluded.
The metric uses the existing inclusive from and exclusive to reporting period. Client reports use the client's home currency, while admin reports use USD.
Periods with no qualifying recoveries return count and amount 0; the revenue currency matches rebillRevenue.

Why it matters

Merchants and reporting teams can quantify the recurring revenue recovered by Flo's dunning process without combining data from separate reports.
Recovery performance can be compared with gross rebill results while keeping provider-managed retries distinct.

Developer notes

This is an additive response change. Existing request parameters, authentication, status codes, rebillCount, and rebillRevenue are unchanged. No SDK upgrade or merchant configuration change is required.
Consumers with strict response validation should update their schema to accept the always-present dunningRecovery object.
Recovered revenue is gross: later refunds, reversals, and chargebacks do not reduce it. Use the existing reversal fields when presenting net performance.
The metric does not reconstruct recovery activity from before this release. Reports remain point-in-time snapshots, so delayed confirmation can update a previously queried historical period.

v1.7.15 - Decline-aware failed rebill recovery #

Flo-owned subscriptions can now recover eligible failed renewals through cadence-aware retries while keeping billing state aligned with confirmed payment outcomes.

22 Aug 2026

Feature

Billing

Subscriptions

Payments

Stripe

PayPal

Flo-owned subscriptions now have a structured recovery window after a failed renewal. Retryable failures remain past_due while Flo tries currently eligible saved payment methods across configured Stripe and PayPal gateways, and the subscription returns to active only after payment is confirmed.

What changed

Retry timing now follows the subscription cadence: daily subscriptions retry through 20 hours, weekly through day 6, monthly through day 27, and annual through day 60. Longer interval counts scale these windows, and retries never cross the next billing boundary.
Each retry checks the currently eligible saved payment methods again, so a method that becomes available during the recovery window can complete the renewal. Methods with a definitive terminal decline are not tried again for that renewal.
Billing dates and the original renewal terms remain unchanged while recovery is in progress. A confirmed payment marks the invoice paid, returns the subscription to active, and advances the next billing cycle exactly once.
Exhausting the retry window, or receiving terminal evidence for every eligible method, marks the subscription expired. If a provider cannot confirm whether a charge settled, Flo stops further charging and holds the outcome for review instead of assuming failure, recovery, or expiry.
Immediate cancellation or pause stops pending recovery attempts. Provider-managed subscriptions continue to follow their existing provider lifecycle.

Why it matters

Merchants have more opportunities to recover recurring revenue after temporary declines or newly available payment methods, without asking the buyer to recreate the subscription.
Subscription, invoice, and billing-date state now reflects confirmed payment evidence throughout recovery, including ambiguous provider outcomes.

Developer notes

No public HTTP route, request or response DTO, SDK export, decline-reason enum, or webhook-envelope schema changed.
A single Flo-owned billing cycle can now emit more than one invoice.payment_failed event, with a distinct event ID for each failed retry. Consumers that previously treated the first failure as terminal should wait for subscription.expired before closing the subscription as unrecovered.
Confirmed recovery emits subscription.updated with active, followed by the established invoice.created, invoice.paid, subscription.renewed, and item.purchased events. An unconfirmed provider outcome can emit subscription.updated with past_due without an invoice.payment_failed event.
No SDK upgrade or merchant configuration migration is required.

v1.7.14 - Reliable buyer-first checkout claims #

Deferred checkout sessions can now identify the buyer before cart data arrives and preserve that buyer when the catalog is attached later.

21 Aug 2026

Fix

Checkout

API

Deferred checkout flows can now collect and attach buyer details before products, currency, and coupons are available. The later catalog claim completes the session without losing the identified buyer, so hosted and embedded checkouts no longer need to force cart data to arrive before the buyer's email.

What changed

PATCH /v1/checkouts/sessions/{id}/claim now accepts an accountData-only claim on a session created with deferDataAttachment: true. The response is 200 OK with buyerIdentified: true and dataAttachmentDeferred: true until the cart is attached.
A later catalog claim preserves the identified buyer and completes data attachment. Replaying the same buyer email is idempotent; a different email continues to return 409 with code checkout_session_buyer_email_mismatch.
An empty claim body is a 200 OK no-op while the session remains deferred. A claim containing currency or couponCodes without products now returns 422 Unprocessable Entity with issue code products_required and field products.

Why it matters

Integrations can follow the order in which checkout data naturally becomes available, including flows that learn the buyer's email before the cart is ready.
Invalid partial catalog claims return a clear, actionable validation response without changing the checkout session.

Developer notes

This change is additive. Existing integrations that attach buyer and catalog data together, or attach the catalog first, continue to work without changes.
Integrations that enumerate issues[].code values can recognize the new products_required result. Include products whenever a claim sends currency or couponCodes.
No SDK update, merchant migration, or operational action is required. The complete catalog must still be attached before payment can proceed.

Backend Changelog

On this page