MCPTool reference
Subscriptions tools
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 764b41d5c7205d6df7eeaeac832fafe882247f5526b1d4d6bc6f98e3eaca7784.
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.
| 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.id | string | Yes | |
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.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. |
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[].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[].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[].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[].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. Default: createdAt DESC. Allowed values: createdAt, endDate, rebillCount, startDate, state, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency. |
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. |
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. |
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. |
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. |
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. Default: createdAt DESC. Allowed values: createdAt, endDate, rebillCount, startDate, state, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency. |
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[].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[].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[].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[].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. |
Settings tools
Arguments, results, errors, and access, confirmation, and retry policy for each Settings tool in FloPay MCP, from the reviewed API contract.
Transactions tools
Arguments, results, errors, and access, confirmation, and retry policy for each Transactions tool in FloPay MCP, from the reviewed API contract.