Arguments, results, errors, and access, confirmation, and retry policy for each Subscriptions tool in FloPay MCP, from the reviewed API contract.

Subscriptions tools

Generated from the FloPay MCP contract version 1, revision cc71a476426ea531d369de5441cde85ab81ab52c9764406e5f09501857d7ed32.

SubscriptionChange_change

Change Subscription Plan

Changes an existing stored subscription to a different plan using the local Flopay subscription UUID. The subscription must belong to the authenticated client. For Flo-owned subscriptions, timeframe selects when the change takes effect. termEnd, or no timeframe, keeps the period-end behavior: the new snapshotted terms bill from the next renewal with no immediate charge, and the change can be withdrawn before then with POST /subscriptions/{id}/change/withdraw. now changes the plan immediately: the prorated difference for the days remaining in the paid current period ((new total - old total) x remainingDays / periodDays, rounded half-up to the minor unit) is charged off-session on the stored payment method and the renewal date is kept. A billing-cadence change charges the new total less the unused value of the current period and re-anchors the renewal to the change instant plus one new period. now is rejected with a typed error, with no charge, when the prorated amount is zero or negative (downgrades stay at the period end) or the subscription is not active with a paid current period; a declined prorated charge leaves the subscription on its old plan and returns the decline contract. A successful now change records a paid proration invoice and emits invoice.created, invoice.paid and subscription.updated, in that order. An uncertain prorated charge (for example a provider timeout) leaves the subscription unchanged and returns subscription_change_charge_uncertain: retry the same change, and the retry reconciles the earlier charge with the provider before charging again, so it never charges twice. While such a charge is unresolved, a different plan change or a withdrawal returns 409 subscription_change_in_progress; cancel and pause are not blocked. If the charge is paid but the subscription changed meanwhile (canceled, paused, renewed or changed), the change is not applied and 409 subscription_change_paid_unapplied is returned. Provider-owned subscriptions retain their existing gateway behavior.

Policy	Value
Operation	`POST /v1/subscriptions/{id}/change`
Class	`mutating`
Risk	`high`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The Flopay subscription UUID to update.

Result

Returns 200 with a JSON body. The stored subscription row after the plan change is applied.

Field	Type	Required	Description
`data`	object	Yes	The stored subscription row after the requested action is applied.
`data.amount`	number or null	Yes	The stored single-unit amount.
`data.buyerBusinessDetails`	object or null	No	The buyer's current business details at this merchant (`customerType`, `legalName`, `address`, `taxId`), or `null` when the buyer has none. Returned by the single-subscription read; omitted from lists.
`data.cancelAt`	string (date-time) or null	Yes	When the subscription is scheduled to cancel.
`data.canceledAt`	string (date-time) or null	Yes	When the subscription was canceled.
`data.checkoutMetadata`	object	No	Immutable non-sensitive client context inherited from the originating checkout.
`data.checkoutSessionId`	string or null	Yes	The originating checkout session UUID when available.
`data.clientId`	string or null	Yes	The authenticated client UUID associated with the subscription row.
`data.createdAt`	string (date-time)	Yes	When the row was created.
`data.currency`	string or null	Yes	The ISO 4217 currency code recorded for the subscription.
`data.endDate`	string (date-time) or null	Yes	When the current subscription term ends.
`data.gateway`	object or null	No	Owning gateway (non-secret fields). Present only when the `gateway` relation is requested.
`data.gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data.gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data.gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data.gateway.id`	string	Yes	Gateway UUID.
`data.gateway.name`	string	Yes	Human-readable name of the gateway account.
`data.gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data.gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data.gatewayId`	string or null	Yes	The gateway configuration UUID used for this subscription when available.
`data.gatewaySubscriptionId`	string	Yes	The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized `flo_<uuid>` identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway.
`data.gatewayType`	string	Yes	The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read `ownership` to tell the two apart. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gatewayUserId`	string or null	Yes	The billing gateway customer identifier when one is known.
`data.metadata`	object or null	Yes	Arbitrary metadata captured with the subscription row.
`data.meteredItems`	array of object	Yes	The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription.
`data.meteredItems[].itemId`	string (uuid)	Yes	The metered item: the catalogue price attached to the plan.
`data.meteredItems[].name`	string	Yes
`data.meteredItems[].unitPrice`	string	Yes	Effective unit price as an exact decimal string (up to 6 places) in the subscription currency.
`data.ownership`	string	Yes	Who owns the billing schedule. `provider` means the gateway holds the subscription object and drives renewals; `flo` means Flopay holds the schedule and drives renewals itself, charging through the gateway named by `gatewayType`. Allowed values: `flo`, `provider`.
`data.pauseState`	string or null	Yes	Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: `scheduled`, `active`.
`data.pausedAt`	string (date-time) or null	Yes	When the subscription was paused.
`data.planDescription`	string or null	Yes	The stored plan description when available.
`data.planId`	string	Yes	The stored plan identifier.
`data.planName`	string	Yes	The stored plan name.
`data.quantity`	number	Yes	The subscribed quantity.
`data.rebillCount`	integer (int32)	Yes	The number of successful renewal charges recorded for the subscription. Minimum: 0.
`data.resumeAt`	string (date-time) or null	Yes	When the subscription will resume.
`data.startDate`	string (date-time) or null	Yes	When the subscription started.
`data.state`	string	Yes	The current subscription state stored in Flopay. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`data.total`	number or null	Yes	The stored total amount.
`data.trialEnd`	string (date-time) or null	Yes	When the trial ends.
`data.updatedAt`	string (date-time)	Yes	When the row was last updated.
`data.usagePeriod`	object or null	Yes	The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. `null` once the subscription has ended, before it has started, and for a provider-owned subscription.
`data.usagePeriod.end`	string (date-time)	Yes	End of the open usage period (exclusive).
`data.usagePeriod.start`	string (date-time)	Yes	Start of the open usage period (inclusive).
`data.userFirstName`	string or null	No	Customer first name when the user relation is loaded.
`data.userGatewayId`	string or null	Yes	The linked internal user gateway row UUID when available.
`data.userLastName`	string or null	No	Customer last name when the user relation is loaded.
`data.userUuid`	string or null	Yes	The Flopay user UUID associated with the subscription.
`data.uuid`	string	Yes	Internal Flopay subscription UUID.

Errors

Status	Description
`400`	The subscription id or request body was invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`424`	The stored subscription could not be resolved or the billing provider could not preview or apply the requested change.

SubscriptionChange_changePreview

Preview Subscription Plan Change

Previews a subscription plan change before it is applied. Use the same payload as the change endpoint to inspect proration and invoice impact. For a Flo-owned subscription the preview is computed locally, writes nothing and calls no billing provider: immediateChargeAmount is the prorated amount timeframe: now would charge today, in minor units (zero for termEnd or no timeframe), and nextChargeAt is the renewal the new terms first bill on. A now change that is not chargeable or not eligible returns the same typed error as the change endpoint.

Policy	Value
Operation	`POST /v1/subscriptions/{id}/change/preview`
Class	`read-only`
Risk	`medium`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The Flopay subscription UUID to preview.

Result

Returns 200 with a JSON body. A preview of the updated plan and any generated invoice calculations.

Field	Type	Required	Description
`data`	object	Yes
`data.activatedAt`	string (date-time)	Yes
`data.currency`	string	No	Flo-owned subscriptions only: the ISO currency of `immediateChargeAmount` and `unitAmount`.
`data.id`	string	Yes
`data.immediateChargeAmount`	number	No	Flo-owned subscriptions only: the prorated amount charged today, in minor units. Zero for `timeframe: termEnd` or no timeframe.
`data.invoiceCollection`	object	Yes
`data.invoiceCollection.chargeInvoice`	object or null	Yes
`data.invoiceCollection.chargeInvoice.currency`	object	Yes
`data.invoiceCollection.chargeInvoice.currency.code`	string	Yes	The ISO 4217 currency code.
`data.invoiceCollection.chargeInvoice.currency.symbol`	string or null	Yes	The display symbol for the currency when available.
`data.invoiceCollection.chargeInvoice.discount`	number	Yes
`data.invoiceCollection.chargeInvoice.id`	string	Yes
`data.invoiceCollection.chargeInvoice.refundableAmount`	number or null	Yes
`data.invoiceCollection.chargeInvoice.subtotal`	number	Yes
`data.invoiceCollection.chargeInvoice.subtotalAfterDiscount`	number	Yes
`data.invoiceCollection.chargeInvoice.tax`	number	Yes
`data.invoiceCollection.chargeInvoice.total`	number	Yes
`data.invoiceCollection.chargeInvoice.type`	string	Yes	Allowed values: `charge`, `credit`, `legacy`.
`data.invoiceCollection.creditInvoices`	array of object or null	Yes
`data.invoiceCollection.creditInvoices[].currency`	object	Yes
`data.invoiceCollection.creditInvoices[].currency.code`	string	Yes	The ISO 4217 currency code.
`data.invoiceCollection.creditInvoices[].currency.symbol`	string or null	Yes	The display symbol for the currency when available.
`data.invoiceCollection.creditInvoices[].discount`	number	Yes
`data.invoiceCollection.creditInvoices[].id`	string	Yes
`data.invoiceCollection.creditInvoices[].refundableAmount`	number or null	Yes
`data.invoiceCollection.creditInvoices[].subtotal`	number	Yes
`data.invoiceCollection.creditInvoices[].subtotalAfterDiscount`	number	Yes
`data.invoiceCollection.creditInvoices[].tax`	number	Yes
`data.invoiceCollection.creditInvoices[].total`	number	Yes
`data.invoiceCollection.creditInvoices[].type`	string	Yes	Allowed values: `charge`, `credit`, `legacy`.
`data.nextChargeAt`	string (date-time) or null	No	Flo-owned subscriptions only: the renewal the new terms first bill on. A billing-cadence change with `timeframe: now` re-anchors it to the change instant plus one new period.
`data.plan`	object	Yes
`data.plan.code`	string	Yes
`data.plan.id`	string	Yes
`data.plan.name`	string	Yes
`data.quantity`	number	Yes
`data.unitAmount`	number	Yes

Errors

Status	Description
`400`	The subscription id or request body was invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`424`	The stored subscription could not be resolved or the billing provider could not preview or apply the requested change.

SubscriptionChange_withdrawChange

Withdraw Scheduled Subscription Plan Change

Withdraws a Flo-owned plan change scheduled for the period end (timeframe: termEnd or no timeframe) before it takes effect. The terms the current period was paid at are restored, the next renewal bills them, and subscription.updated is emitted. Returns subscription_no_pending_change when no change is pending or the boundary has already renewed, and 409 subscription_change_in_progress while an immediate change has an unresolved prorated charge. Provider-owned subscriptions are not supported.

Policy	Value
Operation	`POST /v1/subscriptions/{id}/change/withdraw`
Class	`mutating`
Risk	`high`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The Flopay subscription UUID whose scheduled plan change is withdrawn.

Result

Returns 200 with a JSON body. The stored subscription row after the scheduled plan change is withdrawn.

Field	Type	Required	Description
`data`	object	Yes	The stored subscription row after the requested action is applied.
`data.amount`	number or null	Yes	The stored single-unit amount.
`data.buyerBusinessDetails`	object or null	No	The buyer's current business details at this merchant (`customerType`, `legalName`, `address`, `taxId`), or `null` when the buyer has none. Returned by the single-subscription read; omitted from lists.
`data.cancelAt`	string (date-time) or null	Yes	When the subscription is scheduled to cancel.
`data.canceledAt`	string (date-time) or null	Yes	When the subscription was canceled.
`data.checkoutMetadata`	object	No	Immutable non-sensitive client context inherited from the originating checkout.
`data.checkoutSessionId`	string or null	Yes	The originating checkout session UUID when available.
`data.clientId`	string or null	Yes	The authenticated client UUID associated with the subscription row.
`data.createdAt`	string (date-time)	Yes	When the row was created.
`data.currency`	string or null	Yes	The ISO 4217 currency code recorded for the subscription.
`data.endDate`	string (date-time) or null	Yes	When the current subscription term ends.
`data.gateway`	object or null	No	Owning gateway (non-secret fields). Present only when the `gateway` relation is requested.
`data.gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data.gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data.gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data.gateway.id`	string	Yes	Gateway UUID.
`data.gateway.name`	string	Yes	Human-readable name of the gateway account.
`data.gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data.gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data.gatewayId`	string or null	Yes	The gateway configuration UUID used for this subscription when available.
`data.gatewaySubscriptionId`	string	Yes	The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized `flo_<uuid>` identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway.
`data.gatewayType`	string	Yes	The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read `ownership` to tell the two apart. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gatewayUserId`	string or null	Yes	The billing gateway customer identifier when one is known.
`data.metadata`	object or null	Yes	Arbitrary metadata captured with the subscription row.
`data.meteredItems`	array of object	Yes	The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription.
`data.meteredItems[].itemId`	string (uuid)	Yes	The metered item: the catalogue price attached to the plan.
`data.meteredItems[].name`	string	Yes
`data.meteredItems[].unitPrice`	string	Yes	Effective unit price as an exact decimal string (up to 6 places) in the subscription currency.
`data.ownership`	string	Yes	Who owns the billing schedule. `provider` means the gateway holds the subscription object and drives renewals; `flo` means Flopay holds the schedule and drives renewals itself, charging through the gateway named by `gatewayType`. Allowed values: `flo`, `provider`.
`data.pauseState`	string or null	Yes	Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: `scheduled`, `active`.
`data.pausedAt`	string (date-time) or null	Yes	When the subscription was paused.
`data.planDescription`	string or null	Yes	The stored plan description when available.
`data.planId`	string	Yes	The stored plan identifier.
`data.planName`	string	Yes	The stored plan name.
`data.quantity`	number	Yes	The subscribed quantity.
`data.rebillCount`	integer (int32)	Yes	The number of successful renewal charges recorded for the subscription. Minimum: 0.
`data.resumeAt`	string (date-time) or null	Yes	When the subscription will resume.
`data.startDate`	string (date-time) or null	Yes	When the subscription started.
`data.state`	string	Yes	The current subscription state stored in Flopay. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`data.total`	number or null	Yes	The stored total amount.
`data.trialEnd`	string (date-time) or null	Yes	When the trial ends.
`data.updatedAt`	string (date-time)	Yes	When the row was last updated.
`data.usagePeriod`	object or null	Yes	The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. `null` once the subscription has ended, before it has started, and for a provider-owned subscription.
`data.usagePeriod.end`	string (date-time)	Yes	End of the open usage period (exclusive).
`data.usagePeriod.start`	string (date-time)	Yes	Start of the open usage period (inclusive).
`data.userFirstName`	string or null	No	Customer first name when the user relation is loaded.
`data.userGatewayId`	string or null	Yes	The linked internal user gateway row UUID when available.
`data.userLastName`	string or null	No	Customer last name when the user relation is loaded.
`data.userUuid`	string or null	Yes	The Flopay user UUID associated with the subscription.
`data.uuid`	string	Yes	Internal Flopay subscription UUID.

Errors

Status	Description
`400`	The subscription id or request body was invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`424`	The stored subscription could not be resolved or the billing provider could not preview or apply the requested change.

SubscriptionControl_cancel

Cancel Subscription

Cancel an active subscription using the local Flopay subscription UUID. The subscription must belong to the authenticated client. Flo-owned subscriptions are changed locally without calling a provider subscription API.

Policy	Value
Operation	`PUT /v1/subscriptions/{id}/cancel`
Class	`mutating`
Risk	`critical`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The Flopay subscription UUID to cancel.

Result

Returns 200 with a JSON body. The stored subscription row after the cancellation request is recorded.

Field	Type	Required	Description
`data`	object	Yes	The stored subscription row after the requested action is applied.
`data.amount`	number or null	Yes	The stored single-unit amount.
`data.buyerBusinessDetails`	object or null	No	The buyer's current business details at this merchant (`customerType`, `legalName`, `address`, `taxId`), or `null` when the buyer has none. Returned by the single-subscription read; omitted from lists.
`data.cancelAt`	string (date-time) or null	Yes	When the subscription is scheduled to cancel.
`data.canceledAt`	string (date-time) or null	Yes	When the subscription was canceled.
`data.checkoutMetadata`	object	No	Immutable non-sensitive client context inherited from the originating checkout.
`data.checkoutSessionId`	string or null	Yes	The originating checkout session UUID when available.
`data.clientId`	string or null	Yes	The authenticated client UUID associated with the subscription row.
`data.createdAt`	string (date-time)	Yes	When the row was created.
`data.currency`	string or null	Yes	The ISO 4217 currency code recorded for the subscription.
`data.endDate`	string (date-time) or null	Yes	When the current subscription term ends.
`data.gateway`	object or null	No	Owning gateway (non-secret fields). Present only when the `gateway` relation is requested.
`data.gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data.gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data.gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data.gateway.id`	string	Yes	Gateway UUID.
`data.gateway.name`	string	Yes	Human-readable name of the gateway account.
`data.gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data.gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data.gatewayId`	string or null	Yes	The gateway configuration UUID used for this subscription when available.
`data.gatewaySubscriptionId`	string	Yes	The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized `flo_<uuid>` identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway.
`data.gatewayType`	string	Yes	The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read `ownership` to tell the two apart. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gatewayUserId`	string or null	Yes	The billing gateway customer identifier when one is known.
`data.metadata`	object or null	Yes	Arbitrary metadata captured with the subscription row.
`data.meteredItems`	array of object	Yes	The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription.
`data.meteredItems[].itemId`	string (uuid)	Yes	The metered item: the catalogue price attached to the plan.
`data.meteredItems[].name`	string	Yes
`data.meteredItems[].unitPrice`	string	Yes	Effective unit price as an exact decimal string (up to 6 places) in the subscription currency.
`data.ownership`	string	Yes	Who owns the billing schedule. `provider` means the gateway holds the subscription object and drives renewals; `flo` means Flopay holds the schedule and drives renewals itself, charging through the gateway named by `gatewayType`. Allowed values: `flo`, `provider`.
`data.pauseState`	string or null	Yes	Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: `scheduled`, `active`.
`data.pausedAt`	string (date-time) or null	Yes	When the subscription was paused.
`data.planDescription`	string or null	Yes	The stored plan description when available.
`data.planId`	string	Yes	The stored plan identifier.
`data.planName`	string	Yes	The stored plan name.
`data.quantity`	number	Yes	The subscribed quantity.
`data.rebillCount`	integer (int32)	Yes	The number of successful renewal charges recorded for the subscription. Minimum: 0.
`data.resumeAt`	string (date-time) or null	Yes	When the subscription will resume.
`data.startDate`	string (date-time) or null	Yes	When the subscription started.
`data.state`	string	Yes	The current subscription state stored in Flopay. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`data.total`	number or null	Yes	The stored total amount.
`data.trialEnd`	string (date-time) or null	Yes	When the trial ends.
`data.updatedAt`	string (date-time)	Yes	When the row was last updated.
`data.usagePeriod`	object or null	Yes	The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. `null` once the subscription has ended, before it has started, and for a provider-owned subscription.
`data.usagePeriod.end`	string (date-time)	Yes	End of the open usage period (exclusive).
`data.usagePeriod.start`	string (date-time)	Yes	Start of the open usage period (inclusive).
`data.userFirstName`	string or null	No	Customer first name when the user relation is loaded.
`data.userGatewayId`	string or null	Yes	The linked internal user gateway row UUID when available.
`data.userLastName`	string or null	No	Customer last name when the user relation is loaded.
`data.userUuid`	string or null	Yes	The Flopay user UUID associated with the subscription.
`data.uuid`	string	Yes	Internal Flopay subscription UUID.

Errors

Status	Description
`400`	The subscription id or request body was invalid, or the billing provider rejected the lifecycle transition (for example, reactivating a subscription that is not pending cancellation, pausing a PayPal subscription with a future date, or extending past a non-extendable state).
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`424`	The stored subscription could not be resolved for the authenticated client.

SubscriptionControl_extend

Extend Subscription Term End

Push an active or trialing subscription's term end out to a future date using the local Flopay subscription UUID. The subscription must belong to the authenticated client. Use this for manual term extensions (for example, granting a free month) without generating a proration invoice. The new date must be strictly after the current period end. Flo-owned subscriptions move their local renewal boundary without calling a provider subscription API.

Policy	Value
Operation	`PUT /v1/subscriptions/{id}/extend`
Class	`mutating`
Risk	`high`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The Flopay subscription UUID to extend.

Result

Returns 200 with a JSON body. The stored subscription row after the extension is applied.

Field	Type	Required	Description
`data`	object	Yes	The stored subscription row after the requested action is applied.
`data.amount`	number or null	Yes	The stored single-unit amount.
`data.buyerBusinessDetails`	object or null	No	The buyer's current business details at this merchant (`customerType`, `legalName`, `address`, `taxId`), or `null` when the buyer has none. Returned by the single-subscription read; omitted from lists.
`data.cancelAt`	string (date-time) or null	Yes	When the subscription is scheduled to cancel.
`data.canceledAt`	string (date-time) or null	Yes	When the subscription was canceled.
`data.checkoutMetadata`	object	No	Immutable non-sensitive client context inherited from the originating checkout.
`data.checkoutSessionId`	string or null	Yes	The originating checkout session UUID when available.
`data.clientId`	string or null	Yes	The authenticated client UUID associated with the subscription row.
`data.createdAt`	string (date-time)	Yes	When the row was created.
`data.currency`	string or null	Yes	The ISO 4217 currency code recorded for the subscription.
`data.endDate`	string (date-time) or null	Yes	When the current subscription term ends.
`data.gateway`	object or null	No	Owning gateway (non-secret fields). Present only when the `gateway` relation is requested.
`data.gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data.gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data.gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data.gateway.id`	string	Yes	Gateway UUID.
`data.gateway.name`	string	Yes	Human-readable name of the gateway account.
`data.gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data.gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data.gatewayId`	string or null	Yes	The gateway configuration UUID used for this subscription when available.
`data.gatewaySubscriptionId`	string	Yes	The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized `flo_<uuid>` identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway.
`data.gatewayType`	string	Yes	The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read `ownership` to tell the two apart. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gatewayUserId`	string or null	Yes	The billing gateway customer identifier when one is known.
`data.metadata`	object or null	Yes	Arbitrary metadata captured with the subscription row.
`data.meteredItems`	array of object	Yes	The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription.
`data.meteredItems[].itemId`	string (uuid)	Yes	The metered item: the catalogue price attached to the plan.
`data.meteredItems[].name`	string	Yes
`data.meteredItems[].unitPrice`	string	Yes	Effective unit price as an exact decimal string (up to 6 places) in the subscription currency.
`data.ownership`	string	Yes	Who owns the billing schedule. `provider` means the gateway holds the subscription object and drives renewals; `flo` means Flopay holds the schedule and drives renewals itself, charging through the gateway named by `gatewayType`. Allowed values: `flo`, `provider`.
`data.pauseState`	string or null	Yes	Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: `scheduled`, `active`.
`data.pausedAt`	string (date-time) or null	Yes	When the subscription was paused.
`data.planDescription`	string or null	Yes	The stored plan description when available.
`data.planId`	string	Yes	The stored plan identifier.
`data.planName`	string	Yes	The stored plan name.
`data.quantity`	number	Yes	The subscribed quantity.
`data.rebillCount`	integer (int32)	Yes	The number of successful renewal charges recorded for the subscription. Minimum: 0.
`data.resumeAt`	string (date-time) or null	Yes	When the subscription will resume.
`data.startDate`	string (date-time) or null	Yes	When the subscription started.
`data.state`	string	Yes	The current subscription state stored in Flopay. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`data.total`	number or null	Yes	The stored total amount.
`data.trialEnd`	string (date-time) or null	Yes	When the trial ends.
`data.updatedAt`	string (date-time)	Yes	When the row was last updated.
`data.usagePeriod`	object or null	Yes	The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. `null` once the subscription has ended, before it has started, and for a provider-owned subscription.
`data.usagePeriod.end`	string (date-time)	Yes	End of the open usage period (exclusive).
`data.usagePeriod.start`	string (date-time)	Yes	Start of the open usage period (inclusive).
`data.userFirstName`	string or null	No	Customer first name when the user relation is loaded.
`data.userGatewayId`	string or null	Yes	The linked internal user gateway row UUID when available.
`data.userLastName`	string or null	No	Customer last name when the user relation is loaded.
`data.userUuid`	string or null	Yes	The Flopay user UUID associated with the subscription.
`data.uuid`	string	Yes	Internal Flopay subscription UUID.

Errors

Status	Description
`400`	The subscription id or request body was invalid, or the billing provider rejected the lifecycle transition (for example, reactivating a subscription that is not pending cancellation, pausing a PayPal subscription with a future date, or extending past a non-extendable state).
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`424`	The stored subscription could not be resolved for the authenticated client.

SubscriptionControl_pause

Pause Subscription

Pause a subscription using the local Flopay subscription UUID. The subscription must belong to the authenticated client. Flo-owned subscriptions are paused locally at the requested effective time without calling a provider subscription API.

Policy	Value
Operation	`PUT /v1/subscriptions/{id}/pause`
Class	`mutating`
Risk	`high`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The Flopay subscription UUID to pause.

Result

Returns 200 with a JSON body. The stored subscription row after the pause is applied. pauseState distinguishes a pause that is already in effect ('active') from a future-dated one that is only recorded to start at pausedAt ('scheduled').

Field	Type	Required	Description
`data`	object	Yes	The stored subscription row after the requested action is applied.
`data.amount`	number or null	Yes	The stored single-unit amount.
`data.buyerBusinessDetails`	object or null	No	The buyer's current business details at this merchant (`customerType`, `legalName`, `address`, `taxId`), or `null` when the buyer has none. Returned by the single-subscription read; omitted from lists.
`data.cancelAt`	string (date-time) or null	Yes	When the subscription is scheduled to cancel.
`data.canceledAt`	string (date-time) or null	Yes	When the subscription was canceled.
`data.checkoutMetadata`	object	No	Immutable non-sensitive client context inherited from the originating checkout.
`data.checkoutSessionId`	string or null	Yes	The originating checkout session UUID when available.
`data.clientId`	string or null	Yes	The authenticated client UUID associated with the subscription row.
`data.createdAt`	string (date-time)	Yes	When the row was created.
`data.currency`	string or null	Yes	The ISO 4217 currency code recorded for the subscription.
`data.endDate`	string (date-time) or null	Yes	When the current subscription term ends.
`data.gateway`	object or null	No	Owning gateway (non-secret fields). Present only when the `gateway` relation is requested.
`data.gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data.gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data.gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data.gateway.id`	string	Yes	Gateway UUID.
`data.gateway.name`	string	Yes	Human-readable name of the gateway account.
`data.gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data.gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data.gatewayId`	string or null	Yes	The gateway configuration UUID used for this subscription when available.
`data.gatewaySubscriptionId`	string	Yes	The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized `flo_<uuid>` identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway.
`data.gatewayType`	string	Yes	The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read `ownership` to tell the two apart. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gatewayUserId`	string or null	Yes	The billing gateway customer identifier when one is known.
`data.metadata`	object or null	Yes	Arbitrary metadata captured with the subscription row.
`data.meteredItems`	array of object	Yes	The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription.
`data.meteredItems[].itemId`	string (uuid)	Yes	The metered item: the catalogue price attached to the plan.
`data.meteredItems[].name`	string	Yes
`data.meteredItems[].unitPrice`	string	Yes	Effective unit price as an exact decimal string (up to 6 places) in the subscription currency.
`data.ownership`	string	Yes	Who owns the billing schedule. `provider` means the gateway holds the subscription object and drives renewals; `flo` means Flopay holds the schedule and drives renewals itself, charging through the gateway named by `gatewayType`. Allowed values: `flo`, `provider`.
`data.pauseState`	string or null	Yes	Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: `scheduled`, `active`.
`data.pausedAt`	string (date-time) or null	Yes	When the subscription was paused.
`data.planDescription`	string or null	Yes	The stored plan description when available.
`data.planId`	string	Yes	The stored plan identifier.
`data.planName`	string	Yes	The stored plan name.
`data.quantity`	number	Yes	The subscribed quantity.
`data.rebillCount`	integer (int32)	Yes	The number of successful renewal charges recorded for the subscription. Minimum: 0.
`data.resumeAt`	string (date-time) or null	Yes	When the subscription will resume.
`data.startDate`	string (date-time) or null	Yes	When the subscription started.
`data.state`	string	Yes	The current subscription state stored in Flopay. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`data.total`	number or null	Yes	The stored total amount.
`data.trialEnd`	string (date-time) or null	Yes	When the trial ends.
`data.updatedAt`	string (date-time)	Yes	When the row was last updated.
`data.usagePeriod`	object or null	Yes	The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. `null` once the subscription has ended, before it has started, and for a provider-owned subscription.
`data.usagePeriod.end`	string (date-time)	Yes	End of the open usage period (exclusive).
`data.usagePeriod.start`	string (date-time)	Yes	Start of the open usage period (inclusive).
`data.userFirstName`	string or null	No	Customer first name when the user relation is loaded.
`data.userGatewayId`	string or null	Yes	The linked internal user gateway row UUID when available.
`data.userLastName`	string or null	No	Customer last name when the user relation is loaded.
`data.userUuid`	string or null	Yes	The Flopay user UUID associated with the subscription.
`data.uuid`	string	Yes	Internal Flopay subscription UUID.

Errors

Status	Description
`400`	The subscription id or request body was invalid, or the billing provider rejected the lifecycle transition (for example, reactivating a subscription that is not pending cancellation, pausing a PayPal subscription with a future date, or extending past a non-extendable state).
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`424`	The stored subscription could not be resolved for the authenticated client.

SubscriptionControl_reactivate

Reactivate Subscription

Reactivate a subscription pending deferred cancellation using the local Flopay subscription UUID. The subscription must belong to the authenticated client. Flo-owned subscriptions are changed locally without calling a provider subscription API.

Policy	Value
Operation	`PUT /v1/subscriptions/{id}/reactivate`
Class	`mutating`
Risk	`high`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The Flopay subscription UUID to reactivate.

Result

Returns 200 with a JSON body. The stored subscription row after the reactivation is applied.

Field	Type	Required	Description
`data`	object	Yes	The stored subscription row after the requested action is applied.
`data.amount`	number or null	Yes	The stored single-unit amount.
`data.buyerBusinessDetails`	object or null	No	The buyer's current business details at this merchant (`customerType`, `legalName`, `address`, `taxId`), or `null` when the buyer has none. Returned by the single-subscription read; omitted from lists.
`data.cancelAt`	string (date-time) or null	Yes	When the subscription is scheduled to cancel.
`data.canceledAt`	string (date-time) or null	Yes	When the subscription was canceled.
`data.checkoutMetadata`	object	No	Immutable non-sensitive client context inherited from the originating checkout.
`data.checkoutSessionId`	string or null	Yes	The originating checkout session UUID when available.
`data.clientId`	string or null	Yes	The authenticated client UUID associated with the subscription row.
`data.createdAt`	string (date-time)	Yes	When the row was created.
`data.currency`	string or null	Yes	The ISO 4217 currency code recorded for the subscription.
`data.endDate`	string (date-time) or null	Yes	When the current subscription term ends.
`data.gateway`	object or null	No	Owning gateway (non-secret fields). Present only when the `gateway` relation is requested.
`data.gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data.gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data.gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data.gateway.id`	string	Yes	Gateway UUID.
`data.gateway.name`	string	Yes	Human-readable name of the gateway account.
`data.gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data.gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data.gatewayId`	string or null	Yes	The gateway configuration UUID used for this subscription when available.
`data.gatewaySubscriptionId`	string	Yes	The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized `flo_<uuid>` identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway.
`data.gatewayType`	string	Yes	The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read `ownership` to tell the two apart. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gatewayUserId`	string or null	Yes	The billing gateway customer identifier when one is known.
`data.metadata`	object or null	Yes	Arbitrary metadata captured with the subscription row.
`data.meteredItems`	array of object	Yes	The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription.
`data.meteredItems[].itemId`	string (uuid)	Yes	The metered item: the catalogue price attached to the plan.
`data.meteredItems[].name`	string	Yes
`data.meteredItems[].unitPrice`	string	Yes	Effective unit price as an exact decimal string (up to 6 places) in the subscription currency.
`data.ownership`	string	Yes	Who owns the billing schedule. `provider` means the gateway holds the subscription object and drives renewals; `flo` means Flopay holds the schedule and drives renewals itself, charging through the gateway named by `gatewayType`. Allowed values: `flo`, `provider`.
`data.pauseState`	string or null	Yes	Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: `scheduled`, `active`.
`data.pausedAt`	string (date-time) or null	Yes	When the subscription was paused.
`data.planDescription`	string or null	Yes	The stored plan description when available.
`data.planId`	string	Yes	The stored plan identifier.
`data.planName`	string	Yes	The stored plan name.
`data.quantity`	number	Yes	The subscribed quantity.
`data.rebillCount`	integer (int32)	Yes	The number of successful renewal charges recorded for the subscription. Minimum: 0.
`data.resumeAt`	string (date-time) or null	Yes	When the subscription will resume.
`data.startDate`	string (date-time) or null	Yes	When the subscription started.
`data.state`	string	Yes	The current subscription state stored in Flopay. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`data.total`	number or null	Yes	The stored total amount.
`data.trialEnd`	string (date-time) or null	Yes	When the trial ends.
`data.updatedAt`	string (date-time)	Yes	When the row was last updated.
`data.usagePeriod`	object or null	Yes	The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. `null` once the subscription has ended, before it has started, and for a provider-owned subscription.
`data.usagePeriod.end`	string (date-time)	Yes	End of the open usage period (exclusive).
`data.usagePeriod.start`	string (date-time)	Yes	Start of the open usage period (inclusive).
`data.userFirstName`	string or null	No	Customer first name when the user relation is loaded.
`data.userGatewayId`	string or null	Yes	The linked internal user gateway row UUID when available.
`data.userLastName`	string or null	No	Customer last name when the user relation is loaded.
`data.userUuid`	string or null	Yes	The Flopay user UUID associated with the subscription.
`data.uuid`	string	Yes	Internal Flopay subscription UUID.

Errors

Status	Description
`400`	The subscription id or request body was invalid, or the billing provider rejected the lifecycle transition (for example, reactivating a subscription that is not pending cancellation, pausing a PayPal subscription with a future date, or extending past a non-extendable state).
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`424`	The stored subscription could not be resolved for the authenticated client.

SubscriptionControl_resume

Resume Subscription

Resume a paused subscription using the local Flopay subscription UUID. The subscription must belong to the authenticated client. Flo-owned subscriptions restore local billing eligibility from the effective resume time without calling a provider subscription API.

Policy	Value
Operation	`PUT /v1/subscriptions/{id}/resume`
Class	`mutating`
Risk	`high`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The Flopay subscription UUID to resume.

Result

Returns 200 with a JSON body. The stored subscription row after the resume is applied.

Field	Type	Required	Description
`data`	object	Yes	The stored subscription row after the requested action is applied.
`data.amount`	number or null	Yes	The stored single-unit amount.
`data.buyerBusinessDetails`	object or null	No	The buyer's current business details at this merchant (`customerType`, `legalName`, `address`, `taxId`), or `null` when the buyer has none. Returned by the single-subscription read; omitted from lists.
`data.cancelAt`	string (date-time) or null	Yes	When the subscription is scheduled to cancel.
`data.canceledAt`	string (date-time) or null	Yes	When the subscription was canceled.
`data.checkoutMetadata`	object	No	Immutable non-sensitive client context inherited from the originating checkout.
`data.checkoutSessionId`	string or null	Yes	The originating checkout session UUID when available.
`data.clientId`	string or null	Yes	The authenticated client UUID associated with the subscription row.
`data.createdAt`	string (date-time)	Yes	When the row was created.
`data.currency`	string or null	Yes	The ISO 4217 currency code recorded for the subscription.
`data.endDate`	string (date-time) or null	Yes	When the current subscription term ends.
`data.gateway`	object or null	No	Owning gateway (non-secret fields). Present only when the `gateway` relation is requested.
`data.gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data.gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data.gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data.gateway.id`	string	Yes	Gateway UUID.
`data.gateway.name`	string	Yes	Human-readable name of the gateway account.
`data.gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data.gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data.gatewayId`	string or null	Yes	The gateway configuration UUID used for this subscription when available.
`data.gatewaySubscriptionId`	string	Yes	The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized `flo_<uuid>` identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway.
`data.gatewayType`	string	Yes	The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read `ownership` to tell the two apart. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gatewayUserId`	string or null	Yes	The billing gateway customer identifier when one is known.
`data.metadata`	object or null	Yes	Arbitrary metadata captured with the subscription row.
`data.meteredItems`	array of object	Yes	The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription.
`data.meteredItems[].itemId`	string (uuid)	Yes	The metered item: the catalogue price attached to the plan.
`data.meteredItems[].name`	string	Yes
`data.meteredItems[].unitPrice`	string	Yes	Effective unit price as an exact decimal string (up to 6 places) in the subscription currency.
`data.ownership`	string	Yes	Who owns the billing schedule. `provider` means the gateway holds the subscription object and drives renewals; `flo` means Flopay holds the schedule and drives renewals itself, charging through the gateway named by `gatewayType`. Allowed values: `flo`, `provider`.
`data.pauseState`	string or null	Yes	Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: `scheduled`, `active`.
`data.pausedAt`	string (date-time) or null	Yes	When the subscription was paused.
`data.planDescription`	string or null	Yes	The stored plan description when available.
`data.planId`	string	Yes	The stored plan identifier.
`data.planName`	string	Yes	The stored plan name.
`data.quantity`	number	Yes	The subscribed quantity.
`data.rebillCount`	integer (int32)	Yes	The number of successful renewal charges recorded for the subscription. Minimum: 0.
`data.resumeAt`	string (date-time) or null	Yes	When the subscription will resume.
`data.startDate`	string (date-time) or null	Yes	When the subscription started.
`data.state`	string	Yes	The current subscription state stored in Flopay. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`data.total`	number or null	Yes	The stored total amount.
`data.trialEnd`	string (date-time) or null	Yes	When the trial ends.
`data.updatedAt`	string (date-time)	Yes	When the row was last updated.
`data.usagePeriod`	object or null	Yes	The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. `null` once the subscription has ended, before it has started, and for a provider-owned subscription.
`data.usagePeriod.end`	string (date-time)	Yes	End of the open usage period (exclusive).
`data.usagePeriod.start`	string (date-time)	Yes	Start of the open usage period (inclusive).
`data.userFirstName`	string or null	No	Customer first name when the user relation is loaded.
`data.userGatewayId`	string or null	Yes	The linked internal user gateway row UUID when available.
`data.userLastName`	string or null	No	Customer last name when the user relation is loaded.
`data.userUuid`	string or null	Yes	The Flopay user UUID associated with the subscription.
`data.uuid`	string	Yes	Internal Flopay subscription UUID.

Errors

Status	Description
`400`	The subscription id or request body was invalid, or the billing provider rejected the lifecycle transition (for example, reactivating a subscription that is not pending cancellation, pausing a PayPal subscription with a future date, or extending past a non-extendable state).
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`424`	The stored subscription could not be resolved for the authenticated client.

SubscriptionCreate_create

Create Subscription

Creates a new subscription for an existing Flopay user. The endpoint cascades through the user's gateways (ordered by most-recently-active) and stops on the first provider that successfully creates the subscription. Returns 422 when the user has no user_gateway rows tied to an active gateway and 424 with an attempts[] array when every gateway rejected the request (including payment_method_not_found when the gateway-side customer has no payment method on file).

Policy	Value
Operation	`POST /v1/subscriptions`
Class	`mutating`
Risk	`critical`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

This tool takes no arguments.

Result

Returns 201 with a JSON body. The stored subscription row returned by the first provider that succeeded.

Field	Type	Required	Description
`data`	object	Yes	The stored subscription row after the requested action is applied.
`data.amount`	number or null	Yes	The stored single-unit amount.
`data.buyerBusinessDetails`	object or null	No	The buyer's current business details at this merchant (`customerType`, `legalName`, `address`, `taxId`), or `null` when the buyer has none. Returned by the single-subscription read; omitted from lists.
`data.cancelAt`	string (date-time) or null	Yes	When the subscription is scheduled to cancel.
`data.canceledAt`	string (date-time) or null	Yes	When the subscription was canceled.
`data.checkoutMetadata`	object	No	Immutable non-sensitive client context inherited from the originating checkout.
`data.checkoutSessionId`	string or null	Yes	The originating checkout session UUID when available.
`data.clientId`	string or null	Yes	The authenticated client UUID associated with the subscription row.
`data.createdAt`	string (date-time)	Yes	When the row was created.
`data.currency`	string or null	Yes	The ISO 4217 currency code recorded for the subscription.
`data.endDate`	string (date-time) or null	Yes	When the current subscription term ends.
`data.gateway`	object or null	No	Owning gateway (non-secret fields). Present only when the `gateway` relation is requested.
`data.gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data.gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data.gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data.gateway.id`	string	Yes	Gateway UUID.
`data.gateway.name`	string	Yes	Human-readable name of the gateway account.
`data.gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data.gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data.gatewayId`	string or null	Yes	The gateway configuration UUID used for this subscription when available.
`data.gatewaySubscriptionId`	string	Yes	The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized `flo_<uuid>` identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway.
`data.gatewayType`	string	Yes	The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read `ownership` to tell the two apart. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.gatewayUserId`	string or null	Yes	The billing gateway customer identifier when one is known.
`data.metadata`	object or null	Yes	Arbitrary metadata captured with the subscription row.
`data.meteredItems`	array of object	Yes	The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription.
`data.meteredItems[].itemId`	string (uuid)	Yes	The metered item: the catalogue price attached to the plan.
`data.meteredItems[].name`	string	Yes
`data.meteredItems[].unitPrice`	string	Yes	Effective unit price as an exact decimal string (up to 6 places) in the subscription currency.
`data.ownership`	string	Yes	Who owns the billing schedule. `provider` means the gateway holds the subscription object and drives renewals; `flo` means Flopay holds the schedule and drives renewals itself, charging through the gateway named by `gatewayType`. Allowed values: `flo`, `provider`.
`data.pauseState`	string or null	Yes	Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: `scheduled`, `active`.
`data.pausedAt`	string (date-time) or null	Yes	When the subscription was paused.
`data.planDescription`	string or null	Yes	The stored plan description when available.
`data.planId`	string	Yes	The stored plan identifier.
`data.planName`	string	Yes	The stored plan name.
`data.quantity`	number	Yes	The subscribed quantity.
`data.rebillCount`	integer (int32)	Yes	The number of successful renewal charges recorded for the subscription. Minimum: 0.
`data.resumeAt`	string (date-time) or null	Yes	When the subscription will resume.
`data.startDate`	string (date-time) or null	Yes	When the subscription started.
`data.state`	string	Yes	The current subscription state stored in Flopay. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`data.total`	number or null	Yes	The stored total amount.
`data.trialEnd`	string (date-time) or null	Yes	When the trial ends.
`data.updatedAt`	string (date-time)	Yes	When the row was last updated.
`data.usagePeriod`	object or null	Yes	The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. `null` once the subscription has ended, before it has started, and for a provider-owned subscription.
`data.usagePeriod.end`	string (date-time)	Yes	End of the open usage period (exclusive).
`data.usagePeriod.start`	string (date-time)	Yes	Start of the open usage period (inclusive).
`data.userFirstName`	string or null	No	Customer first name when the user relation is loaded.
`data.userGatewayId`	string or null	Yes	The linked internal user gateway row UUID when available.
`data.userLastName`	string or null	No	Customer last name when the user relation is loaded.
`data.userUuid`	string or null	Yes	The Flopay user UUID associated with the subscription.
`data.uuid`	string	Yes	Internal Flopay subscription UUID.

Errors

Status	Description
`400`	The request body failed validation.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`422`	The user has no `user_gateway` rows tied to an active gateway. The response body shape matches the failure DTO with an empty `attempts[]` array.
`424`	Every eligible gateway rejected the subscription, or a Flo-owned start remains unresolved. The response includes `attempts[]`; an unresolved start uses `subscription_start_pending` as both the message and attempt reason, without declaring the subscription failed.

SubscriptionPlan_getAll

List Subscription Plans

List all active subscription plans available for the authenticated client and resolved product provider credentials.

Policy	Value
Operation	`GET /v1/subscriptions/plans`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

This tool takes no arguments.

Result

Returns 200 with a JSON body. The active subscription plans available for the authenticated client.

Field	Type	Required	Description
`data`	array of object	Yes
`data[].code`	string	Yes
`data[].currencies`	array of object	Yes
`data[].currencies[].amount`	number	Yes
`data[].currencies[].code`	string	Yes	The ISO 4217 currency code.
`data[].currencies[].setupFee`	number	Yes
`data[].currencies[].symbol`	string or null	Yes	The display symbol for the currency when available.
`data[].description`	string	Yes
`data[].id`	string	Yes
`data[].intervalLength`	number	Yes
`data[].intervalUnit`	string	Yes	Allowed values: `day`, `month`, `week`.
`data[].name`	string	Yes
`data[].totalBillingCycles`	number	Yes
`data[].trialLength`	number	Yes
`data[].trialUnit`	string	Yes	Allowed values: `day`, `month`, `week`.

Errors

Status	Description
`400`	The request was invalid or the product provider credentials could not be resolved.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`424`	Throws in cases where Billing service cannot get data from billing provider.

SubscriptionPreview_getAllActiveV2

List Active Stored Subscriptions

Get all active subscriptions stored in the local Flopay subscription table for a user email. The email lookup is scoped to the authenticated client.

Policy	Value
Operation	`GET /v2/subscriptions/active`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`email`	query	string	Yes	User email used to find stored subscriptions for the authenticated client.

Result

Returns 200 with a JSON body. The active subscription rows stored in Flopay for the requested user email.

Field	Type	Required	Description
`data`	array of object	Yes	Subscription rows stored for the requested user.
`data[].amount`	number or null	Yes	The stored single-unit amount.
`data[].buyerBusinessDetails`	object or null	No	The buyer's current business details at this merchant (`customerType`, `legalName`, `address`, `taxId`), or `null` when the buyer has none. Returned by the single-subscription read; omitted from lists.
`data[].cancelAt`	string (date-time) or null	Yes	When the subscription is scheduled to cancel.
`data[].canceledAt`	string (date-time) or null	Yes	When the subscription was canceled.
`data[].checkoutMetadata`	object	No	Immutable non-sensitive client context inherited from the originating checkout.
`data[].checkoutSessionId`	string or null	Yes	The originating checkout session UUID when available.
`data[].clientId`	string or null	Yes	The authenticated client UUID associated with the subscription row.
`data[].createdAt`	string (date-time)	Yes	When the row was created.
`data[].currency`	string or null	Yes	The ISO 4217 currency code recorded for the subscription.
`data[].endDate`	string (date-time) or null	Yes	When the current subscription term ends.
`data[].gateway`	object or null	No	Owning gateway (non-secret fields). Present only when the `gateway` relation is requested.
`data[].gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data[].gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data[].gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data[].gateway.id`	string	Yes	Gateway UUID.
`data[].gateway.name`	string	Yes	Human-readable name of the gateway account.
`data[].gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data[].gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data[].gatewayId`	string or null	Yes	The gateway configuration UUID used for this subscription when available.
`data[].gatewaySubscriptionId`	string	Yes	The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized `flo_<uuid>` identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway.
`data[].gatewayType`	string	Yes	The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read `ownership` to tell the two apart. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].gatewayUserId`	string or null	Yes	The billing gateway customer identifier when one is known.
`data[].metadata`	object or null	Yes	Arbitrary metadata captured with the subscription row.
`data[].meteredItems`	array of object	Yes	The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription.
`data[].meteredItems[].itemId`	string (uuid)	Yes	The metered item: the catalogue price attached to the plan.
`data[].meteredItems[].name`	string	Yes
`data[].meteredItems[].unitPrice`	string	Yes	Effective unit price as an exact decimal string (up to 6 places) in the subscription currency.
`data[].ownership`	string	Yes	Who owns the billing schedule. `provider` means the gateway holds the subscription object and drives renewals; `flo` means Flopay holds the schedule and drives renewals itself, charging through the gateway named by `gatewayType`. Allowed values: `flo`, `provider`.
`data[].pauseState`	string or null	Yes	Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: `scheduled`, `active`.
`data[].pausedAt`	string (date-time) or null	Yes	When the subscription was paused.
`data[].planDescription`	string or null	Yes	The stored plan description when available.
`data[].planId`	string	Yes	The stored plan identifier.
`data[].planName`	string	Yes	The stored plan name.
`data[].quantity`	number	Yes	The subscribed quantity.
`data[].rebillCount`	integer (int32)	Yes	The number of successful renewal charges recorded for the subscription. Minimum: 0.
`data[].resumeAt`	string (date-time) or null	Yes	When the subscription will resume.
`data[].startDate`	string (date-time) or null	Yes	When the subscription started.
`data[].state`	string	Yes	The current subscription state stored in Flopay. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`data[].total`	number or null	Yes	The stored total amount.
`data[].trialEnd`	string (date-time) or null	Yes	When the trial ends.
`data[].updatedAt`	string (date-time)	Yes	When the row was last updated.
`data[].usagePeriod`	object or null	Yes	The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. `null` once the subscription has ended, before it has started, and for a provider-owned subscription.
`data[].usagePeriod.end`	string (date-time)	Yes	End of the open usage period (exclusive).
`data[].usagePeriod.start`	string (date-time)	Yes	Start of the open usage period (inclusive).
`data[].userFirstName`	string or null	No	Customer first name when the user relation is loaded.
`data[].userGatewayId`	string or null	Yes	The linked internal user gateway row UUID when available.
`data[].userLastName`	string or null	No	Customer last name when the user relation is loaded.
`data[].userUuid`	string or null	Yes	The Flopay user UUID associated with the subscription.
`data[].uuid`	string	Yes	Internal Flopay subscription UUID.

Errors

Status	Description
`400`	The `email` query parameter was missing or invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`424`	Throws in cases where Billing service cannot get data from billing provider.

SubscriptionRead_exportSubscriptions

Export subscriptions

Exports the resource-owned list as a point-in-time framed stream. Reuses this endpoint's list query filters and sort. current_page preserves page/limit; all_matching ignores page/limit while preserving filters and sort. Client routes require an OAuth client_user owner/admin token; admin routes require a single valid clientId selector; partner routes require an authenticated partner seat and are scoped to that partner. Ordinary members, client Basic auth, and cross-tenant requests are rejected.

Policy	Value
Operation	`POST /v1/subscriptions/exports`
Class	`read-only`
Risk	`medium`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`aggregate`
Roles	`owner`, `admin`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`page`	query	integer	No	1-based page number for paginated list endpoints. Default: `1`. Minimum: 1.
`limit`	query	integer	No	Maximum number of records to return per page. Default: `20`. Minimum: 1. Maximum: 100.
`sort`	query	string	No	Sort by one allowed field. Use exactly one of `sort[asc]` or `sort[desc]`. Allowed fields: `createdAt`, `endDate`, `rebillCount`, `startDate`, `state`, `updatedAt`, `gateway.id`, `gateway.code`, `gateway.name`, `gateway.providerType`, `gateway.environment`, `gateway.currency`, `gateway.sessionMode`. Default: `createdAt` DESC. Allowed values: `createdAt`, `endDate`, `rebillCount`, `startDate`, `state`, `updatedAt`, `gateway.id`, `gateway.code`, `gateway.name`, `gateway.providerType`, `gateway.environment`, `gateway.currency`, `gateway.sessionMode`.
`relation`	query	string	No	Comma-separated relation aliases to include. Allowed aliases: `gateway`. Unknown aliases return 400.
`createdAt`	query	string (date) or string (date-time)	No	Subscription creation timestamp. Date-only range bounds use UTC calendar dates: `[gte]` starts at 00:00 UTC on the selected date and `[lte]` includes the complete selected date. Full timestamps compare as exact instants. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`email`	query	string	No	Email address of the user that owns the subscription. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`endDate`	query	string (date-time)	No	Current subscription term end timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`gatewayType`	query	string	No	The billing provider that recorded this subscription. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`ownership`	query	string	No	Who drives the renewals: `provider` (the gateway holds the subscription object) or `flo` (Flopay holds the schedule and charges through `gatewayType`). Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `flo`, `provider`.
`planCode`	query	string	No	The plan identifier recorded on the subscription (alias for `planId`). Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]` `[search]`. `[in]` accepts comma-separated values; blank entries return 400. `[search]` is case-insensitive text contains matching.
`planId`	query	string	No	The plan identifier recorded on the subscription. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]` `[search]`. `[in]` accepts comma-separated values; blank entries return 400. `[search]` is case-insensitive text contains matching.
`planName`	query	string	No	The plan name recorded on the subscription. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`rebillCount`	query	number	No	Number of successful renewal charges recorded for the subscription. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`startDate`	query	string (date-time)	No	Subscription start timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`state`	query	string	No	Subscription state. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`updatedAt`	query	string (date-time)	No	Subscription update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`userUuid`	query	string	No	Linked Flopay user UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`uuid`	query	string	No	Flopay subscription UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`fields`	body	array of string	No	Stable export field keys in output order.
`format`	body	string	Yes	Allowed values: `csv`, `json`.
`scope`	body	string	Yes	Allowed values: `current_page`, `all_matching`.

Result

Returns 200 as application/vnd.flopay.export-stream.v1. Versioned length-prefixed export stream containing started/progress/completed_file/file_chunk/complete frames.

Errors

Status	Description
`400`	Invalid scope, format, field key, query parameter, client selector, row cap, or plaintext byte cap.
`401`	Authentication is missing or invalid.
`403`	The actor is not allowed to export this resource.
`429`	Export capacity exhausted. Retry-After is set to 60 seconds.
`503`	Exports disabled or export storage unavailable.

SubscriptionRead_findOne

Get Subscription

Returns a single stored subscription for the authenticated client.

Policy	Value
Operation	`GET /v1/subscriptions/{id}`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`id`	path	string	Yes
`relation`	query	string	No	Comma-separated relation aliases to include. Allowed aliases: `gateway`. Unknown aliases return 400.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`amount`	number or null	Yes	The stored single-unit amount.
`buyerBusinessDetails`	object or null	No	The buyer's current business details at this merchant (`customerType`, `legalName`, `address`, `taxId`), or `null` when the buyer has none. Returned by the single-subscription read; omitted from lists.
`cancelAt`	string (date-time) or null	Yes	When the subscription is scheduled to cancel.
`canceledAt`	string (date-time) or null	Yes	When the subscription was canceled.
`checkoutMetadata`	object	No	Immutable non-sensitive client context inherited from the originating checkout.
`checkoutSessionId`	string or null	Yes	The originating checkout session UUID when available.
`clientId`	string or null	Yes	The authenticated client UUID associated with the subscription row.
`createdAt`	string (date-time)	Yes	When the row was created.
`currency`	string or null	Yes	The ISO 4217 currency code recorded for the subscription.
`endDate`	string (date-time) or null	Yes	When the current subscription term ends.
`gateway`	object or null	No	Owning gateway (non-secret fields). Present only when the `gateway` relation is requested.
`gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`gateway.id`	string	Yes	Gateway UUID.
`gateway.name`	string	Yes	Human-readable name of the gateway account.
`gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`gatewayId`	string or null	Yes	The gateway configuration UUID used for this subscription when available.
`gatewaySubscriptionId`	string	Yes	The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized `flo_<uuid>` identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway.
`gatewayType`	string	Yes	The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read `ownership` to tell the two apart. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`gatewayUserId`	string or null	Yes	The billing gateway customer identifier when one is known.
`metadata`	object or null	Yes	Arbitrary metadata captured with the subscription row.
`meteredItems`	array of object	Yes	The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription.
`meteredItems[].itemId`	string (uuid)	Yes	The metered item: the catalogue price attached to the plan.
`meteredItems[].name`	string	Yes
`meteredItems[].unitPrice`	string	Yes	Effective unit price as an exact decimal string (up to 6 places) in the subscription currency.
`ownership`	string	Yes	Who owns the billing schedule. `provider` means the gateway holds the subscription object and drives renewals; `flo` means Flopay holds the schedule and drives renewals itself, charging through the gateway named by `gatewayType`. Allowed values: `flo`, `provider`.
`pauseState`	string or null	Yes	Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: `scheduled`, `active`.
`pausedAt`	string (date-time) or null	Yes	When the subscription was paused.
`planDescription`	string or null	Yes	The stored plan description when available.
`planId`	string	Yes	The stored plan identifier.
`planName`	string	Yes	The stored plan name.
`quantity`	number	Yes	The subscribed quantity.
`rebillCount`	integer (int32)	Yes	The number of successful renewal charges recorded for the subscription. Minimum: 0.
`resumeAt`	string (date-time) or null	Yes	When the subscription will resume.
`startDate`	string (date-time) or null	Yes	When the subscription started.
`state`	string	Yes	The current subscription state stored in Flopay. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`total`	number or null	Yes	The stored total amount.
`trialEnd`	string (date-time) or null	Yes	When the trial ends.
`updatedAt`	string (date-time)	Yes	When the row was last updated.
`usagePeriod`	object or null	Yes	The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. `null` once the subscription has ended, before it has started, and for a provider-owned subscription.
`usagePeriod.end`	string (date-time)	Yes	End of the open usage period (exclusive).
`usagePeriod.start`	string (date-time)	Yes	Start of the open usage period (inclusive).
`userFirstName`	string or null	No	Customer first name when the user relation is loaded.
`userGatewayId`	string or null	Yes	The linked internal user gateway row UUID when available.
`userLastName`	string or null	No	Customer last name when the user relation is loaded.
`userUuid`	string or null	Yes	The Flopay user UUID associated with the subscription.
`uuid`	string	Yes	Internal Flopay subscription UUID.

Errors

Status	Description
`400`	The supplied path, query, or filter values were invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`404`	No subscription with the requested id exists for this client.

SubscriptionRead_list

List Subscriptions

Returns paginated subscriptions for the authenticated client. Supports page, limit, sort[asc|desc], optional email, and whitelisted filters for uuid, state, gatewayType, planCode/planId, planName, rebillCount, startDate, endDate, createdAt, and updatedAt.

Policy	Value
Operation	`GET /v1/subscriptions`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`page`	query	integer	No	1-based page number for paginated list endpoints. Default: `1`. Minimum: 1.
`limit`	query	integer	No	Maximum number of records to return per page. Default: `20`. Minimum: 1. Maximum: 100.
`sort`	query	string	No	Sort by one allowed field. Use exactly one of `sort[asc]` or `sort[desc]`. Allowed fields: `createdAt`, `endDate`, `rebillCount`, `startDate`, `state`, `updatedAt`, `gateway.id`, `gateway.code`, `gateway.name`, `gateway.providerType`, `gateway.environment`, `gateway.currency`, `gateway.sessionMode`. Default: `createdAt` DESC. Allowed values: `createdAt`, `endDate`, `rebillCount`, `startDate`, `state`, `updatedAt`, `gateway.id`, `gateway.code`, `gateway.name`, `gateway.providerType`, `gateway.environment`, `gateway.currency`, `gateway.sessionMode`.
`relation`	query	string	No	Comma-separated relation aliases to include. Allowed aliases: `gateway`. Unknown aliases return 400.
`createdAt`	query	string (date) or string (date-time)	No	Subscription creation timestamp. Date-only range bounds use UTC calendar dates: `[gte]` starts at 00:00 UTC on the selected date and `[lte]` includes the complete selected date. Full timestamps compare as exact instants. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`email`	query	string	No	Email address of the user that owns the subscription. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`endDate`	query	string (date-time)	No	Current subscription term end timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`gatewayType`	query	string	No	The billing provider that recorded this subscription. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`ownership`	query	string	No	Who drives the renewals: `provider` (the gateway holds the subscription object) or `flo` (Flopay holds the schedule and charges through `gatewayType`). Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `flo`, `provider`.
`planCode`	query	string	No	The plan identifier recorded on the subscription (alias for `planId`). Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]` `[search]`. `[in]` accepts comma-separated values; blank entries return 400. `[search]` is case-insensitive text contains matching.
`planId`	query	string	No	The plan identifier recorded on the subscription. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]` `[search]`. `[in]` accepts comma-separated values; blank entries return 400. `[search]` is case-insensitive text contains matching.
`planName`	query	string	No	The plan name recorded on the subscription. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`rebillCount`	query	number	No	Number of successful renewal charges recorded for the subscription. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`startDate`	query	string (date-time)	No	Subscription start timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`state`	query	string	No	Subscription state. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`updatedAt`	query	string (date-time)	No	Subscription update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`userUuid`	query	string	No	Linked Flopay user UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`uuid`	query	string	No	Flopay subscription UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`data`	array of object	Yes
`data[].amount`	number or null	Yes	The stored single-unit amount.
`data[].buyerBusinessDetails`	object or null	No	The buyer's current business details at this merchant (`customerType`, `legalName`, `address`, `taxId`), or `null` when the buyer has none. Returned by the single-subscription read; omitted from lists.
`data[].cancelAt`	string (date-time) or null	Yes	When the subscription is scheduled to cancel.
`data[].canceledAt`	string (date-time) or null	Yes	When the subscription was canceled.
`data[].checkoutMetadata`	object	No	Immutable non-sensitive client context inherited from the originating checkout.
`data[].checkoutSessionId`	string or null	Yes	The originating checkout session UUID when available.
`data[].clientId`	string or null	Yes	The authenticated client UUID associated with the subscription row.
`data[].createdAt`	string (date-time)	Yes	When the row was created.
`data[].currency`	string or null	Yes	The ISO 4217 currency code recorded for the subscription.
`data[].endDate`	string (date-time) or null	Yes	When the current subscription term ends.
`data[].gateway`	object or null	No	Owning gateway (non-secret fields). Present only when the `gateway` relation is requested.
`data[].gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data[].gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data[].gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data[].gateway.id`	string	Yes	Gateway UUID.
`data[].gateway.name`	string	Yes	Human-readable name of the gateway account.
`data[].gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data[].gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data[].gatewayId`	string or null	Yes	The gateway configuration UUID used for this subscription when available.
`data[].gatewaySubscriptionId`	string	Yes	The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized `flo_<uuid>` identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway.
`data[].gatewayType`	string	Yes	The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read `ownership` to tell the two apart. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].gatewayUserId`	string or null	Yes	The billing gateway customer identifier when one is known.
`data[].metadata`	object or null	Yes	Arbitrary metadata captured with the subscription row.
`data[].meteredItems`	array of object	Yes	The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription.
`data[].meteredItems[].itemId`	string (uuid)	Yes	The metered item: the catalogue price attached to the plan.
`data[].meteredItems[].name`	string	Yes
`data[].meteredItems[].unitPrice`	string	Yes	Effective unit price as an exact decimal string (up to 6 places) in the subscription currency.
`data[].ownership`	string	Yes	Who owns the billing schedule. `provider` means the gateway holds the subscription object and drives renewals; `flo` means Flopay holds the schedule and drives renewals itself, charging through the gateway named by `gatewayType`. Allowed values: `flo`, `provider`.
`data[].pauseState`	string or null	Yes	Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: `scheduled`, `active`.
`data[].pausedAt`	string (date-time) or null	Yes	When the subscription was paused.
`data[].planDescription`	string or null	Yes	The stored plan description when available.
`data[].planId`	string	Yes	The stored plan identifier.
`data[].planName`	string	Yes	The stored plan name.
`data[].quantity`	number	Yes	The subscribed quantity.
`data[].rebillCount`	integer (int32)	Yes	The number of successful renewal charges recorded for the subscription. Minimum: 0.
`data[].resumeAt`	string (date-time) or null	Yes	When the subscription will resume.
`data[].startDate`	string (date-time) or null	Yes	When the subscription started.
`data[].state`	string	Yes	The current subscription state stored in Flopay. Allowed values: `active`, `canceled`, `expired`, `failed`, `future`, `paused`, `past_due`.
`data[].total`	number or null	Yes	The stored total amount.
`data[].trialEnd`	string (date-time) or null	Yes	When the trial ends.
`data[].updatedAt`	string (date-time)	Yes	When the row was last updated.
`data[].usagePeriod`	object or null	Yes	The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. `null` once the subscription has ended, before it has started, and for a provider-owned subscription.
`data[].usagePeriod.end`	string (date-time)	Yes	End of the open usage period (exclusive).
`data[].usagePeriod.start`	string (date-time)	Yes	Start of the open usage period (inclusive).
`data[].userFirstName`	string or null	No	Customer first name when the user relation is loaded.
`data[].userGatewayId`	string or null	Yes	The linked internal user gateway row UUID when available.
`data[].userLastName`	string or null	No	Customer last name when the user relation is loaded.
`data[].userUuid`	string or null	Yes	The Flopay user UUID associated with the subscription.
`data[].uuid`	string	Yes	Internal Flopay subscription UUID.
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`400`	The supplied path, query, or filter values were invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.

SubscriptionRecovery_list

List Subscription Recovery Campaigns

Returns the authenticated client subscription recovery campaigns most recent first, including every persisted recovery round. The response uses the shared paginated list contract.

Policy	Value
Operation	`GET /v1/subscriptions/{id}/recovery`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`id`	path	string	Yes
`page`	query	integer	No	1-based page number for paginated list endpoints. Default: `1`. Minimum: 1.
`limit`	query	integer	No	Maximum number of records to return per page. Default: `20`. Minimum: 1. Maximum: 100.
`sort`	query	string	No	Sort by one allowed field. Use exactly one of `sort[asc]` or `sort[desc]`. Allowed fields: `billingCycleAt`, `createdAt`, `nextRetryAt`, `status`. Default: `billingCycleAt` DESC. Allowed values: `billingCycleAt`, `createdAt`, `nextRetryAt`, `status`.
`relation`	query	string	No	This endpoint does not support relation aliases. Supplying relation returns 400.
`billingCycleAt`	query	string (date-time)	No	Original billing-cycle timestamp for the recovery campaign. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`createdAt`	query	string (date-time)	No	Recovery campaign creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`nextRetryAt`	query	string (date-time)	No	Next persisted recovery retry timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`policyVersion`	query	string	No	Frozen policy version used by the campaign. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`status`	query	string	No	Recovery campaign lifecycle status. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `active`, `operational_retry`, `recovered`, `exhausted`, `non_retryable`, `manual_review`, `stopped`.
`uuid`	query	string	No	Recovery campaign UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`data`	array of object	Yes
`data[].billingCycleAt`	string (date-time)	Yes	Original failed billing-cycle timestamp.
`data[].createdAt`	string (date-time)	Yes
`data[].exhaustedAt`	string (date-time) or null	Yes
`data[].interval`	string	Yes	Frozen subscription billing cadence. Allowed values: `day`, `week`, `month`, `year`.
`data[].intervalCount`	number	Yes	Frozen number of cadence units per billing cycle.
`data[].manualReviewAt`	string (date-time) or null	Yes
`data[].nextRetryAt`	string (date-time) or null	Yes	Next persisted recovery retry, when one remains.
`data[].originalAmount`	number	Yes	Original invoice amount in major currency units.
`data[].originalCurrency`	string	Yes	Original ISO-4217 invoice currency.
`data[].policyVersion`	string	Yes	Frozen policy version used for this campaign.
`data[].recoveredAt`	string (date-time) or null	Yes
`data[].rounds`	array of object	Yes
`data[].rounds[].attemptCount`	number	Yes	Number of provider attempts recorded within this round.
`data[].rounds[].completedAt`	string (date-time) or null	Yes
`data[].rounds[].normalizedDeclineReason`	string or null	Yes	Allowed values: `INSUFFICIENT_FUNDS`, `DO_NOT_HONOUR`, `TOO_MANY_ATTEMPTS`, `PARTIAL_APPROVAL`, `PAYMENT_GATEWAY_ERROR`, `TECHNICAL_ERROR`, `RETRYABLE_DECLINE`, `UNSUPPORTED_CARD_PURCHASE`, `USER_ERROR`, `CVV_INVALID`, `AVS_FAIL`, `POSTCODE_INVALID`, `3DS_FAIL`, `EXCEEDS_CARD_LIMIT`, `CLIENT_ERROR`, `UNKNOWN_DECLINE_REASON`.
`data[].rounds[].roundNumber`	number	Yes	Zero-based original attempt or positive scheduled recovery-round number.
`data[].rounds[].scheduledAt`	string (date-time)	Yes	Persisted timestamp committed for this round.
`data[].rounds[].startedAt`	string (date-time) or null	Yes
`data[].rounds[].status`	string	Yes	Allowed values: `scheduled`, `processing`, `retryable`, `non_retryable`, `operationally_uncertain`, `succeeded`, `canceled`.
`data[].status`	string	Yes	Allowed values: `active`, `operational_retry`, `recovered`, `exhausted`, `non_retryable`, `manual_review`, `stopped`.
`data[].stoppedAt`	string (date-time) or null	Yes
`data[].uuid`	string (uuid)	Yes
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`400`	The subscription id or list query parameters were invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication with the required scope is required.
`404`	No subscription with the requested id exists for this client.

SubscriptionStats_get

Subscription rebill stats

Returns successful rebill count, gross revenue, period-end average rebill length, terminal churn, and gross-rebill lifetime value for one half-open period.

Policy	Value
Operation	`GET /v1/subscriptions/stats`
Class	`read-only`
Risk	`medium`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`aggregate`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`to`	query	string	Yes	Exclusive reporting-period end as an offset ISO-8601 instant.
`from`	query	string	Yes	Inclusive reporting-period start as an offset ISO-8601 instant.
`ownership`	query	string	No	Limit the complete snapshot to canonical Flo-managed renewals. Omit to preserve the provider-neutral historical population. Allowed values: `flo`.

Result

Returns 200 with a JSON body. One coherent subscription rebill snapshot.

Field	Type	Required	Description
`averageLifetimeValue`	object or null	Yes
`averageLifetimeValue.amount`	number	No	Minimum: 0.
`averageLifetimeValue.currency`	string	No	Minimum length: 3. Maximum length: 3.
`averageRebillLength`	number or null	Yes	Minimum: 0.
`context`	object	Yes
`context.appliedFilters`	array of object	Yes	Additional filters applied after the authoritative tenant boundary. Empty for merchant calls.
`context.appliedFilters[].field`	string	Yes
`context.appliedFilters[].operator`	string	Yes	Allowed values: `eq`.
`context.appliedFilters[].value`	string	Yes
`context.authoritativeLinks`	array of object	Yes	Relative authenticated Flo API links for verifying authoritative source records.
`context.authoritativeLinks[].href`	string	Yes
`context.authoritativeLinks[].rel`	string	Yes
`context.consistency`	object	Yes	The consistency model and its operator-facing freshness caveat.
`context.consistency.model`	string	Yes	Allowed values: `eventual`.
`context.consistency.note`	string	Yes
`context.currency`	object	Yes	Reporting-currency basis and immutable daily FX snapshots for home/platform totals. Source amounts remain separately segmented.
`context.currency.fx`	object	Yes
`context.currency.fx.applied`	boolean	Yes	Whether this aggregate contains monetary values that were FX-valued.
`context.currency.fx.effectiveDateTimezone`	string	Yes	Allowed values: `UTC`.
`context.currency.fx.method`	string	Yes	Allowed values: `daily-exact-or-prior`.
`context.currency.fx.provisional`	boolean	Yes
`context.currency.fx.snapshots`	array of object	Yes
`context.currency.fx.snapshots[].provisional`	boolean	Yes
`context.currency.fx.snapshots[].valuationDate`	string (date)	Yes
`context.currency.fx.snapshots[].version`	integer	Yes	Minimum: 1.
`context.currency.homeCurrency`	string or null	Yes	Minimum length: 3. Maximum length: 3.
`context.currency.reportingCurrency`	string	Yes	Minimum length: 3. Maximum length: 3.
`context.currency.reportingCurrencyBasis`	string	Yes	Allowed values: `client-home`, `platform-usd`.
`context.dataAsOf`	string (date-time)	Yes	The persisted-data observation boundary for this response.
`context.generatedAt`	string (date-time)	Yes	When the API generated this response.
`context.statusSemantics`	array of object	Yes	Canonical definitions and time bases for statuses and outcomes used in the response.
`context.statusSemantics[].appliesTo`	array of string	Yes
`context.statusSemantics[].code`	string	Yes
`context.statusSemantics[].description`	string	Yes
`context.statusSemantics[].timeBasis`	string	Yes	Allowed values: `created-at`, `financial-effective-at`, `billing-cycle-at`, `attempt-outcome-at`.
`context.tenantScope`	object	Yes	The explicit client-selection mode used by the authenticated backend query.
`context.tenantScope.clientId`	string or null	Yes
`context.tenantScope.kind`	string	Yes	Allowed values: `authenticated-client`, `selected-client`, `all-clients`.
`context.timeRange`	object	Yes	The explicit half-open UTC reporting window applied to the aggregate.
`context.timeRange.bounds`	string	Yes	Allowed values: `[from,to)`.
`context.timeRange.from`	string (date-time)	Yes
`context.timeRange.timezone`	string	Yes	Allowed values: `UTC`.
`context.timeRange.to`	string (date-time)	Yes
`dunningRecovery`	object	Yes	Gross successful rebills recovered by Flo-owned dunning retry rounds. This is an additive subset of rebillCount and rebillRevenue; ordinary first-attempt rebills and provider-managed retries are excluded.
`dunningRecovery.recoveredRebillCount`	integer	Yes	Minimum: 0.
`dunningRecovery.recoveredRebillRevenue`	object	Yes
`dunningRecovery.recoveredRebillRevenue.amount`	number	Yes	Minimum: 0.
`dunningRecovery.recoveredRebillRevenue.currency`	string	Yes	Minimum length: 3. Maximum length: 3.
`dunningTimingPerformance`	object	Yes	Client-scoped comparison of default and evidence-optimized dunning campaigns whose original billing-cycle due instant falls in the requested half-open period.
`dunningTimingPerformance.baseline`	object	Yes
`dunningTimingPerformance.baseline.attempts`	integer	Yes	Minimum: 0.
`dunningTimingPerformance.baseline.averageTimeToRecoveryHours`	number or null	Yes	Minimum: 0.
`dunningTimingPerformance.baseline.campaignCount`	integer	Yes	Minimum: 0.
`dunningTimingPerformance.baseline.isProvisional`	boolean	Yes	Whether this cohort revenue used provisional FX. This does not change the existing top-level isProvisional semantics.
`dunningTimingPerformance.baseline.recoveredRevenue`	object	Yes
`dunningTimingPerformance.baseline.recoveredRevenue.amount`	number	Yes	Minimum: 0.
`dunningTimingPerformance.baseline.recoveredRevenue.currency`	string	Yes	Minimum length: 3. Maximum length: 3.
`dunningTimingPerformance.baseline.successfulRecoveries`	integer	Yes	Minimum: 0.
`dunningTimingPerformance.cohortBasis`	string	Yes	Allowed values: `billing_cycle_at`.
`dunningTimingPerformance.optimized`	object	Yes
`dunningTimingPerformance.optimized.attempts`	integer	Yes	Minimum: 0.
`dunningTimingPerformance.optimized.averageTimeToRecoveryHours`	number or null	Yes	Minimum: 0.
`dunningTimingPerformance.optimized.campaignCount`	integer	Yes	Minimum: 0.
`dunningTimingPerformance.optimized.isProvisional`	boolean	Yes	Whether this cohort revenue used provisional FX. This does not change the existing top-level isProvisional semantics.
`dunningTimingPerformance.optimized.recoveredRevenue`	object	Yes
`dunningTimingPerformance.optimized.recoveredRevenue.amount`	number	Yes	Minimum: 0.
`dunningTimingPerformance.optimized.recoveredRevenue.currency`	string	Yes	Minimum length: 3. Maximum length: 3.
`dunningTimingPerformance.optimized.successfulRecoveries`	integer	Yes	Minimum: 0.
`from`	string (date-time)	Yes
`isProvisional`	boolean	Yes
`rebillChargebacks`	object	Yes	Deprecated compatibility alias for `rebillDisputes`. Same values as `rebillDisputes`. Removal is tracked separately.
`rebillChargebacks.amount`	number	No	FX-valued charged-back amount in the same reporting currency as `rebillRevenue`, each chargeback money movement valued at its own effective date.
`rebillChargebacks.count`	integer	No	Chargeback events reversing rebills in this period. Minimum: 0.
`rebillChargebacks.percentageOfRebillRevenue`	number or null	No	Charged-back amount divided by gross rebill revenue from exact unrounded totals, HALF_UP to two places; null when gross rebill revenue is zero and not clamped above 100%.
`rebillChargebacks.percentageOfRebills`	number or null	No	Chargeback count divided by the gross rebill count, HALF_UP to two places; null when the gross rebill count is zero and not clamped above 100%.
`rebillChurnCoverage`	object or null	Yes
`rebillChurnCoverage.covered`	integer	No	Minimum: 0.
`rebillChurnCoverage.represented`	integer	No	Minimum: 0.
`rebillChurnRate`	number or null	Yes	Minimum: 0. Maximum: 100.
`rebillChurnUnavailableReason`	string or null	Yes	Allowed values: `insufficient_lifecycle_coverage`.
`rebillCount`	number	Yes	Minimum: 0.
`rebillDisputes`	object	Yes	Disputes (actual Stripe and PayPal chargebacks) attributed to subscription renewal charges by their own money-movement effective date (issued-period / occurrence basis). A dispute against the first charge of a subscription is a checkout sale and is reported on the checkout figures, not here. Each dispute money movement is counted once. Network warnings are Pre-Dispute Alerts and are not included.
`rebillDisputes.amount`	number	No	FX-valued disputed amount in the same reporting currency as `rebillRevenue`, each Dispute money movement valued at its own effective date.
`rebillDisputes.count`	integer	No	Dispute events reversing rebills in this period. Minimum: 0.
`rebillDisputes.percentageOfRebillRevenue`	number or null	No	Disputed amount divided by gross rebill revenue from exact unrounded totals, HALF_UP to two places; null when gross rebill revenue is zero and not clamped above 100%.
`rebillDisputes.percentageOfRebills`	number or null	No	Dispute count divided by the gross rebill count, HALF_UP to two places; null when the gross rebill count is zero and not clamped above 100%.
`rebillRefunds`	object	Yes	Refunds attributed to subscription renewal charges by their own financial effective date (issued-period / occurrence basis). A refund against the first charge of a subscription (including a trial conversion) is a checkout sale and is reported on the checkout figures, not here. Each refund is counted once.
`rebillRefunds.amount`	number	No	FX-valued refunded amount in the same reporting currency as `rebillRevenue`, each refund valued at its own financial effective date.
`rebillRefunds.count`	integer	No	Refund events reversing rebills in this period. Minimum: 0.
`rebillRefunds.percentageOfRebillRevenue`	number or null	No	Refunded amount divided by gross rebill revenue from exact unrounded totals, HALF_UP to two places; null when gross rebill revenue is zero and not clamped above 100%.
`rebillRefunds.percentageOfRebills`	number or null	No	Refund count divided by the gross rebill count, HALF_UP to two places; null when the gross rebill count is zero and not clamped above 100%.
`rebillRevenue`	object	Yes
`rebillRevenue.amount`	number	No	Minimum: 0.
`rebillRevenue.currency`	string	No	Minimum length: 3. Maximum length: 3.
`renewalOutcomes`	object	Yes	Authoritative current outcomes for distinct reportable renewal billing cycles whose immutable scheduled due instant is in the requested half-open period. Opening charges, trial conversions, and retries are excluded as separate cycles.
`renewalOutcomes.overdueCycleCount`	integer	Yes	Minimum: 0.
`renewalOutcomes.overduePercentage`	number or null	Yes	Overdue cycles divided by all reportable renewal cycles, as a percentage rounded HALF_UP to two decimal places; null when there are no reportable cycles. Minimum: 0. Maximum: 100.
`renewalOutcomes.rebilledPercentage`	number or null	Yes	Successful cycles divided by successful plus terminally failed cycles, as a percentage rounded HALF_UP to two decimal places; null when there are no settled cycles. Minimum: 0. Maximum: 100.
`renewalOutcomes.successfulCycleCount`	integer	Yes	Minimum: 0.
`renewalOutcomes.terminallyFailedCycleCount`	integer	Yes	Minimum: 0.
`renewalOutcomes.totalCycleCount`	integer	Yes	Minimum: 0.
`sourceCurrencySegments`	array of object	Yes	Gross source amounts grouped by uppercase ISO currency. Amounts are summed exactly then rounded once to that source currency minor unit; no counts are repeated here.
`sourceCurrencySegments[].currency`	string	Yes	Minimum length: 3. Maximum length: 3.
`sourceCurrencySegments[].disputeAmount`	number	Yes
`sourceCurrencySegments[].dunningTimingRecoveredAmounts`	object	No
`sourceCurrencySegments[].dunningTimingRecoveredAmounts.baseline`	number	Yes
`sourceCurrencySegments[].dunningTimingRecoveredAmounts.optimized`	number	Yes
`sourceCurrencySegments[].rebillAmount`	number	Yes
`sourceCurrencySegments[].recoveredRebillAmount`	number	Yes
`sourceCurrencySegments[].refundAmount`	number	Yes
`to`	string (date-time)	Yes

Errors

Status	Description
`401`	Client Basic authentication or OAuth2 bearer authentication is required.

Site navigation

Subscriptions tools

Subscriptions tools

SubscriptionChange_change

SubscriptionChange_changePreview

SubscriptionChange_withdrawChange

SubscriptionControl_cancel

SubscriptionControl_extend

SubscriptionControl_pause

SubscriptionControl_reactivate

SubscriptionControl_resume

SubscriptionCreate_create

SubscriptionPlan_getAll

SubscriptionPreview_getAllActiveV2

SubscriptionRead_exportSubscriptions

SubscriptionRead_findOne

SubscriptionRead_list

SubscriptionRecovery_list

SubscriptionStats_get

On this page

Subscriptions tools

Subscriptions toolsCopy Anchor Link

SubscriptionChange_changeCopy Anchor Link

SubscriptionChange_changePreviewCopy Anchor Link

SubscriptionChange_withdrawChangeCopy Anchor Link

SubscriptionControl_cancelCopy Anchor Link

SubscriptionControl_extendCopy Anchor Link

SubscriptionControl_pauseCopy Anchor Link

SubscriptionControl_reactivateCopy Anchor Link

SubscriptionControl_resumeCopy Anchor Link

SubscriptionCreate_createCopy Anchor Link

SubscriptionPlan_getAllCopy Anchor Link

SubscriptionPreview_getAllActiveV2Copy Anchor Link

SubscriptionRead_exportSubscriptionsCopy Anchor Link

SubscriptionRead_findOneCopy Anchor Link

SubscriptionRead_listCopy Anchor Link

SubscriptionRecovery_listCopy Anchor Link

SubscriptionStats_getCopy Anchor Link

On this page

Subscriptions tools

SubscriptionChange_change

SubscriptionChange_changePreview

SubscriptionChange_withdrawChange

SubscriptionControl_cancel

SubscriptionControl_extend

SubscriptionControl_pause

SubscriptionControl_reactivate

SubscriptionControl_resume

SubscriptionCreate_create

SubscriptionPlan_getAll

SubscriptionPreview_getAllActiveV2

SubscriptionRead_exportSubscriptions

SubscriptionRead_findOne

SubscriptionRead_list

SubscriptionRecovery_list

SubscriptionStats_get