MCPTool reference
Users tools
Arguments, results, errors, and access, confirmation, and retry policy for each Users tool in FloPay MCP, from the reviewed API contract.
Users tools
Generated from the FloPay MCP contract version 1, revision cc71a476426ea531d369de5441cde85ab81ab52c9764406e5f09501857d7ed32.
InvoicePreview_list
List User Invoices
Returns locally persisted invoice records for the supplied user id, ingested via provider webhooks. The user id must belong to the authenticated client. Supports page, limit, sort[asc|desc], and whitelisted filters for uuid, state, total, paidAt, createdAt, and updatedAt. Invalid list parameters return 400.
| Policy | Value |
|---|---|
| Operation | GET /v1/users/{id}/invoices |
| 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 (uuid) | Yes | The Flopay user UUID scoped to the authenticated client. |
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, paidAt, total, updatedAt. Default: createdAt DESC. Allowed values: createdAt, paidAt, total, updatedAt. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
createdAt | query | string (date-time) | No | Invoice creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
paidAt | query | string (date-time) | No | Invoice paid timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
state | query | string | No | Invoice 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: open, pending, processing, pastDue, paid, closed, failed, voided, unknown. |
total | query | number | No | Invoice total amount. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
updatedAt | query | string (date-time) | No | Invoice 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 invoice 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. A paginated list of invoices for the requested user.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | Invoices returned for the requested user. |
data[].billingReason | string or null | No | Provider-reported billing reason. |
data[].buyerBusinessDetails | object or null | No | The buyer's business details at this merchant as they stood when Flo created the invoice: customerType (business or individual), legalName, address (street1, street2, city, region, postalCode, ISO 3166-1 alpha-2 country) and taxId (type, normalised value). A later change to the buyer's details reaches only the next invoice. null when the buyer had none, and for invoices issued by a payment provider. |
data[].createdAt | string (date-time) | Yes | When the invoice was created. |
data[].currency | string or null | No | |
data[].gateway | object or null | No | Owning gateway (non-secret fields). Present when the gateway relation is loaded. |
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[].gatewayInvoiceId | string or null | No | The invoice identifier in the billing provider (e.g. Stripe in_…). Null only briefly while a one-time purchase invoice is being minted at the gateway. |
data[].gatewayType | string | Yes | The billing provider that produced this invoice. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].hostedInvoiceUrl | string or null | No | The invoice's hosted page: no sign-in, behind an unguessable token. For invoices FloPay issues itself it shows both parties' identity, each line, the total and the tax note. Provider invoices carry the provider's page. null when the invoice has none. |
data[].id | string | Yes | The Flopay invoice UUID. |
data[].invoiceNumber | string or null | No | The invoice number. FloPay numbers the invoices it issues itself per merchant as <prefix><sequence> (the merchant's prefix, default INV-, and a sequence zero-padded to 6 digits, e.g. INV-000001); a number is never reused or changed. Provider invoices keep the provider's number. null when the invoice has none. |
data[].invoicePdfUrl | string or null | No | The invoice's PDF, a sibling of hostedInvoiceUrl with the same content and the same access rule. null when the invoice has none. |
data[].paidAt | string (date-time) or null | No | When the invoice was paid by the provider. |
data[].state | string | Yes | The current invoice state. Allowed values: open, pending, processing, pastDue, paid, closed, failed, voided, unknown. |
data[].total | number or null | No | |
data[].transaction | object | No | Linked Flopay transaction (non-secret fields incl. metadata). Present only when the transaction relation is loaded and a transaction settled this invoice. |
data[].transaction.amount | number | Yes | |
data[].transaction.authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
data[].transaction.authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
data[].transaction.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].transaction.checkoutSessionId | string or null | No | Originating checkout session UUID. |
data[].transaction.createdAt | string (date-time) | Yes | Record creation timestamp. |
data[].transaction.currency | string | Yes | |
data[].transaction.description | string or null | Yes | |
data[].transaction.effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
data[].transaction.financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
data[].transaction.floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
data[].transaction.floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
data[].transaction.gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
data[].transaction.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].transaction.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].transaction.gateway.environment | string | Yes | Allowed values: stage, production. |
data[].transaction.gateway.id | string | Yes | Gateway UUID. |
data[].transaction.gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].transaction.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].transaction.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].transaction.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[].transaction.gatewayChargeId | string or null | No | Original gateway charge identifier. |
data[].transaction.gatewayPaymentIntentId | string or null | No | Opaque provider payment-object identifier, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility. |
data[].transaction.gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
data[].transaction.gatewayTransactionId | string or null | No | Gateway transaction identifier. |
data[].transaction.id | string | Yes | |
data[].transaction.metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
data[].transaction.occurredAt | string (date-time) | Yes | |
data[].transaction.refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
data[].transaction.refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
data[].transaction.refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
data[].transaction.refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
data[].transaction.status | string | Yes | |
data[].transaction.subscription | object | No | Linked subscription (non-secret fields incl. metadata). Present only when the subscription relation is loaded and the payment is tied to a subscription. |
data[].transaction.subscription.amount | number or null | Yes | The stored single-unit amount. |
data[].transaction.subscription.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[].transaction.subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
data[].transaction.subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
data[].transaction.subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].transaction.subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
data[].transaction.subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
data[].transaction.subscription.createdAt | string (date-time) | Yes | When the row was created. |
data[].transaction.subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
data[].transaction.subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
data[].transaction.subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
data[].transaction.subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].transaction.subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].transaction.subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
data[].transaction.subscription.gateway.id | string | Yes | Gateway UUID. |
data[].transaction.subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].transaction.subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].transaction.subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].transaction.subscription.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[].transaction.subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
data[].transaction.subscription.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[].transaction.subscription.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[].transaction.subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
data[].transaction.subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
data[].transaction.subscription.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[].transaction.subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
data[].transaction.subscription.meteredItems[].name | string | Yes | |
data[].transaction.subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
data[].transaction.subscription.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[].transaction.subscription.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[].transaction.subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
data[].transaction.subscription.planDescription | string or null | Yes | The stored plan description when available. |
data[].transaction.subscription.planId | string | Yes | The stored plan identifier. |
data[].transaction.subscription.planName | string | Yes | The stored plan name. |
data[].transaction.subscription.quantity | number | Yes | The subscribed quantity. |
data[].transaction.subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
data[].transaction.subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
data[].transaction.subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
data[].transaction.subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
data[].transaction.subscription.total | number or null | Yes | The stored total amount. |
data[].transaction.subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
data[].transaction.subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
data[].transaction.subscription.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[].transaction.subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
data[].transaction.subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
data[].transaction.subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].transaction.subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
data[].transaction.subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].transaction.subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
data[].transaction.subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
data[].transaction.subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
data[].transaction.type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
data[].transaction.userEmail | string or null | No | Customer email when the user relation is loaded. |
data[].transaction.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].transaction.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].transaction.userUuid | string or null | No | Linked Flopay user UUID. |
data[].transactionType | string or null | No | Provider-reported transaction type. |
data[].transactionUuid | string or null | No | Linked Flopay transaction UUID. |
data[].updatedAt | string (date-time) | Yes | When the invoice was last updated. |
data[].userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].userUuid | string or null | No | Linked Flopay user UUID. |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The request path or query parameters 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 user with the supplied id exists for the authenticated client. |
PaymentMethods_delete
Delete Payment Method
Deletes one saved payment method of any type (card, PayPal, wallet or APM) within the authenticated client scope. The method must belong to the resolved client and its user must be linked to that client. Stripe funding is reassigned to an eligible replacement of the same type before provider and vault cleanup; linked PayPal funding requires payer authorization. A wallet Flo can charge is deleted as a card is. A saved method that is not charged (a bank debit) has its provider handle released before it is tombstoned. Durable checkpoints make a 502 response safe to retry, and deleting an already-completed tombstone returns 204. A blocked deletion leaves the method intact.
| Policy | Value |
|---|---|
| Operation | DELETE /v1/payment-methods/{id} |
| 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 | Yes |
Result
Returns 204 with no body. The payment method was deleted or was already deleted.
Errors
| Status | Description |
|---|---|
400 | The payment method id was not a valid UUID. |
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 accessible payment method exists. Missing ids, foreign-gateway methods, and methods for users not linked to the authenticated client are indistinguishable. |
409 | Deletion is blocked by active payment activity, a linked subscription without an eligible replacement, or PayPal funding that requires payer authorization. |
502 | Provider reassignment, deletion, vault cleanup, or verification failed. The stable error contract includes additive provider-neutral recovery guidance. |
PaymentMethods_list
List Payment Methods
Returns paginated saved payment methods of every type for the authenticated client: cards, PayPal, and saved wallets and alternative payment methods (APMs). By default, each Flo card is projected as its oldest binding while filters match every account-specific binding; legacy methods without a Flo card identity remain one row each. view=binding explicitly returns one row per gateway binding. Only methods that belong to the client AND whose user is linked to the client are returned. Supports page, limit, sort[asc|desc], and whitelisted filters for uuid, userUuid, type, provider, status, createdAt, and updatedAt; type[eq] / type[in] accept card, paypal and the saved wallet and APM types, and combine with status. Methods Flo can charge come first (cards, PayPal, and Apple Pay or Google Pay wallets saved for off-session use), then saved methods that are not charged (bank debits), each in the requested sort order; total counts both and a page never exceeds limit. Every row carries additive methodType and a safe displayLabel (null for cards). The response exposes display fields only: vault tokens, provider payment method and customer ids, client secrets, full account identifiers, and billing addresses are never returned. Invalid list parameters return 400.
| Policy | Value |
|---|---|
| Operation | GET /v1/payment-methods |
| 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 |
|---|---|---|---|---|
view | query | string | No | Response presentation. Defaults to flo_card, which returns one stable row per Flo card; binding returns one row per gateway binding. Allowed values: binding, flo_card. |
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, updatedAt. Default: createdAt DESC. Allowed values: createdAt, updatedAt. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
createdAt | query | string (date-time) | No | Payment method creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
provider | query | string | No | The gateway provider that vaulted the payment method. 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. |
status | query | string | No | Payment method 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: pending, active, deleted. |
type | query | string | No | Saved payment method type: card, paypal, or a saved wallet or alternative payment method (APM) type such as apple_pay, google_pay, sepa_debit or us_bank_account. Use type[eq] for one type or type[in] for several; it combines with 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: card, paypal, apple_pay, google_pay, sepa_debit, us_bank_account. |
updatedAt | query | string (date-time) | No | Payment method 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 payment method 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. A paginated list of saved payment methods for the authenticated client.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].brand | string or null | No | Card brand as reported by the gateway (free-text, e.g. "visa"). Null for non-card types. |
data[].createdAt | string (date-time) | Yes | When the payment method row was created. |
data[].displayLabel | string or null | No | Safe, human-readable label for non-card methods: the wallet or APM name (for example Apple Pay), or PayPal with a masked account email. Never contains tokens or full account identifiers. Null for cards, which keep brand and lastFour. Additive. |
data[].expiryMonth | number or null | No | Card expiry month (1-12). Null for non-card types. |
data[].expiryYear | number or null | No | Card expiry year (four digits). Null for non-card types. |
data[].floCardId | string | No | Gateway-agnostic Flo card UUID. Omitted for saved methods created before Flo card identity. |
data[].gateway | object or null | No | Owning gateway (non-secret fields). Present when the gateway relation is loaded. |
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[].gateways | array of object | No | Gateway accounts with a binding to this Flo card. Omitted for saved methods created before Flo card identity. |
data[].gateways[].code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].gateways[].currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].gateways[].environment | string | Yes | Allowed values: stage, production. |
data[].gateways[].id | string | Yes | Gateway UUID. |
data[].gateways[].name | string | Yes | Human-readable name of the gateway account. |
data[].gateways[].providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].gateways[].publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].gateways[].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[].id | string | Yes | Flopay payment method UUID. |
data[].isPreferred | boolean | No | Whether this Flo card is the customer preference. Omitted for legacy saved methods. |
data[].lastFour | string or null | No | Last four digits of the card. Null for non-card types. |
data[].methodType | string | No | Method type identifier, the same identifier the setup flow uses: card, paypal, or a wallet / APM type such as apple_pay, google_pay, sepa_debit or us_bank_account. Additive. Allowed values: card, paypal, apple_pay, google_pay, sepa_debit, us_bank_account. |
data[].payerEmail | string or null | No | Payer email for PayPal, kept unchanged for compatibility (displayLabel carries the masked form). Null for cards, wallets and APMs. |
data[].status | string | Yes | Payment method lifecycle status. Every method type uses the same values: pending until verified, active when usable, deleted for a deletion tombstone. Allowed values: pending, active, deleted. |
data[].type | string | Yes | Stored payment method type: card, paypal, or the type of a saved wallet or APM (for example apple_pay or sepa_debit). Always the same value as methodType. Allowed values: card, paypal, apple_pay, google_pay, sepa_debit, us_bank_account. |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The sort, filter, or pagination query parameters 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. |
Timelines_list
List Timelines
Returns a paginated list of customer timelines for the authenticated client. Each row is a full TimelineDto including the user's merged, chronologically-ordered events (checkout sessions, transactions, subscriptions, invoices, and payment methods). Rows are ordered by their most recent event (occurredAt, default DESC), surfacing the most recently active customers first. Supports page, limit, sort[asc|desc], and whitelisted filters for userUuid, kind, and an occurredAt date range, which narrow the events that make up each timeline. Invalid list parameters return 400.
| Policy | Value |
|---|---|
| Operation | GET /v1/timelines |
| 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: occurredAt. Default: occurredAt DESC. Allowed values: occurredAt. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
kind | query | string | No | Normalised event source kind. Keeps only events of the supplied kind(s). 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: checkout_session, transaction, subscription, invoice, payment_method, dispute, chargeback_alert, pre_dispute_alert. |
occurredAt | query | string (date-time) | No | Event timestamp. Bands the events that make up each timeline. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
userUuid | query | string | No | Flopay user UUID. Scopes the list to a single user timeline. 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. A paginated list of customer timelines for the authenticated client.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].eventCount | number | Yes | Number of events in the timeline. |
data[].events | array of object | Yes | The merged events, ordered oldest → newest. |
data[].events[].amount | number or null | Yes | Amount in major units, or null when the source carries no amount. |
data[].events[].client | object or null | Yes | The merchant (client) that owns this event's underlying record. Always the authenticated client on the client-facing endpoint; on the admin endpoint it identifies the owning merchant per event so a timeline spanning clients can be labelled (e.g. by client.slug). Null only if the client is unresolvable. |
data[].events[].client.slug | string | Yes | The merchant (client) slug, for labelling the event in the dashboard. |
data[].events[].client.uuid | string | Yes | The merchant (client) UUID that owns the underlying record. |
data[].events[].currency | string or null | Yes | ISO-4217 currency code, or null. |
data[].events[].id | string | Yes | Stable graph-node id. Existing resource projections use <kind>:<resourceUuid>; append-only payment lifecycle entries add their persisted transition UUID so multiple events can share one resource. Each later subscription, payment method, dispute or Pre-Dispute Alert state change adds its own <kind>:<resourceUuid>:lifecycle:<key> node instead of rewriting the first node. |
data[].events[].kind | string | Yes | The normalised source kind for this event. Allowed values: checkout_session, transaction, subscription, invoice, payment_method, dispute, chargeback_alert, pre_dispute_alert. |
data[].events[].metadata | object or null | Yes | Optional non-sensitive passthrough metadata, or null. A subscription whose current state has no recorded transition time is one creation-dated node with { "transitionTimeUnknown": true }. |
data[].events[].occurredAt | string (date-time) | Yes | ISO-8601 timestamp the event occurred at. The chronological sort key for the timeline. |
data[].events[].parentUuid | string or null | Yes | FK-derived link to a related event's resourceUuid (a timeline edge), or null when there is no related event in this timeline. |
data[].events[].rebillSequence | integer or null | Yes | The chronological 1-based sequence of this completed subscription rebill, or null when this event is not the completed payment or directly linked invoice for a canonical rebill. Minimum: 1. |
data[].events[].resourceUuid | string | Yes | The underlying record id, for deep-linking to its detail page. |
data[].events[].status | string or null | Yes | Underlying resource status (drives the dashboard status badge), or null. |
data[].events[].title | string | Yes | Short human label, e.g. a plan name or "Checkout session". |
data[].firstEventAt | string (date-time) or null | Yes | Timestamp of the oldest event, or null when the timeline is empty. |
data[].futureEvents | array of object | Yes | Known-future events for this customer's Flo-managed subscriptions, ordered soonest → latest. Each is scheduled, not extrapolated; the array is empty when nothing is committed (including for customers whose subscriptions are all provider-managed). |
data[].futureEvents[].amount | number or null | Yes | The amount that will be charged, in major units. Populated for subscription.rebill and subscription.recovery_retry; null for events that move no money. |
data[].futureEvents[].client | object or null | Yes | The merchant that owns the subscription, or null when it is unresolvable. |
data[].futureEvents[].client.slug | string | Yes | The merchant (client) slug, for labelling the event in the dashboard. |
data[].futureEvents[].client.uuid | string | Yes | The merchant (client) UUID that owns the underlying record. |
data[].futureEvents[].code | string | Yes | What is scheduled to happen. Drives the dashboard label for the event. Allowed values: subscription.start, subscription.trial_end, subscription.rebill, subscription.recovery_retry, subscription.pause, subscription.resume, subscription.cancel. |
data[].futureEvents[].currency | string or null | Yes | ISO-4217 currency code, or null with no amount. |
data[].futureEvents[].expectedAt | string (date-time) | Yes | ISO-8601 timestamp the event is scheduled for. Chronological sort key, and the basis for the relative countdown the dashboard renders. Always in the future at the moment of the response. |
data[].futureEvents[].id | string | Yes | Stable graph-node id, future:<code>:<resourceUuid>. |
data[].futureEvents[].rebillSequence | integer or null | Yes | The next chronological rebill sequence for subscription.rebill, or null for every other future event. Minimum: 1. |
data[].futureEvents[].resourceUuid | string | Yes | The subscription this event is scheduled against: the same uuid as its subscription event in events, so the dashboard can anchor the projection to the node it belongs to. |
data[].futureEvents[].title | string | Yes | Short human label: the subscription plan name. |
data[].lastEventAt | string (date-time) or null | Yes | Timestamp of the newest event, or null when the timeline is empty. |
data[].userEmail | string or null | Yes | The user email, or null when the user row is not resolvable. |
data[].userFirstName | string or null | Yes | The user first name (empty string when the user is unnamed), or null when the user row is not resolvable. |
data[].userLastName | string or null | Yes | The user last name (empty string when the user is unnamed), or null when the user row is not resolvable. |
data[].userUuid | string | Yes | The Flopay user UUID this timeline belongs to. |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The list query parameters were invalid, or record was called without a valid userUuid. |
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. |
Timelines_record
Get User Timeline
Returns a single user's full timeline for the authenticated client: every persisted source event merged into one chronological stream, ordered oldest → newest. The required userUuid query parameter selects the user; a missing, blank, or malformed userUuid returns 400. A user with no events for this client that is not linked to it returns 404.
| Policy | Value |
|---|---|
| Operation | GET /v1/timelines/record |
| 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 |
|---|---|---|---|---|
userUuid | query | string (uuid) | Yes | The Flopay user UUID whose timeline to return. Required. |
Result
Returns 200 with a JSON body. The requested user timeline for the authenticated client.
| Field | Type | Required | Description |
|---|---|---|---|
eventCount | number | Yes | Number of events in the timeline. |
events | array of object | Yes | The merged events, ordered oldest → newest. |
events[].amount | number or null | Yes | Amount in major units, or null when the source carries no amount. |
events[].client | object or null | Yes | The merchant (client) that owns this event's underlying record. Always the authenticated client on the client-facing endpoint; on the admin endpoint it identifies the owning merchant per event so a timeline spanning clients can be labelled (e.g. by client.slug). Null only if the client is unresolvable. |
events[].client.slug | string | Yes | The merchant (client) slug, for labelling the event in the dashboard. |
events[].client.uuid | string | Yes | The merchant (client) UUID that owns the underlying record. |
events[].currency | string or null | Yes | ISO-4217 currency code, or null. |
events[].id | string | Yes | Stable graph-node id. Existing resource projections use <kind>:<resourceUuid>; append-only payment lifecycle entries add their persisted transition UUID so multiple events can share one resource. Each later subscription, payment method, dispute or Pre-Dispute Alert state change adds its own <kind>:<resourceUuid>:lifecycle:<key> node instead of rewriting the first node. |
events[].kind | string | Yes | The normalised source kind for this event. Allowed values: checkout_session, transaction, subscription, invoice, payment_method, dispute, chargeback_alert, pre_dispute_alert. |
events[].metadata | object or null | Yes | Optional non-sensitive passthrough metadata, or null. A subscription whose current state has no recorded transition time is one creation-dated node with { "transitionTimeUnknown": true }. |
events[].occurredAt | string (date-time) | Yes | ISO-8601 timestamp the event occurred at. The chronological sort key for the timeline. |
events[].parentUuid | string or null | Yes | FK-derived link to a related event's resourceUuid (a timeline edge), or null when there is no related event in this timeline. |
events[].rebillSequence | integer or null | Yes | The chronological 1-based sequence of this completed subscription rebill, or null when this event is not the completed payment or directly linked invoice for a canonical rebill. Minimum: 1. |
events[].resourceUuid | string | Yes | The underlying record id, for deep-linking to its detail page. |
events[].status | string or null | Yes | Underlying resource status (drives the dashboard status badge), or null. |
events[].title | string | Yes | Short human label, e.g. a plan name or "Checkout session". |
firstEventAt | string (date-time) or null | Yes | Timestamp of the oldest event, or null when the timeline is empty. |
futureEvents | array of object | Yes | Known-future events for this customer's Flo-managed subscriptions, ordered soonest → latest. Each is scheduled, not extrapolated; the array is empty when nothing is committed (including for customers whose subscriptions are all provider-managed). |
futureEvents[].amount | number or null | Yes | The amount that will be charged, in major units. Populated for subscription.rebill and subscription.recovery_retry; null for events that move no money. |
futureEvents[].client | object or null | Yes | The merchant that owns the subscription, or null when it is unresolvable. |
futureEvents[].client.slug | string | Yes | The merchant (client) slug, for labelling the event in the dashboard. |
futureEvents[].client.uuid | string | Yes | The merchant (client) UUID that owns the underlying record. |
futureEvents[].code | string | Yes | What is scheduled to happen. Drives the dashboard label for the event. Allowed values: subscription.start, subscription.trial_end, subscription.rebill, subscription.recovery_retry, subscription.pause, subscription.resume, subscription.cancel. |
futureEvents[].currency | string or null | Yes | ISO-4217 currency code, or null with no amount. |
futureEvents[].expectedAt | string (date-time) | Yes | ISO-8601 timestamp the event is scheduled for. Chronological sort key, and the basis for the relative countdown the dashboard renders. Always in the future at the moment of the response. |
futureEvents[].id | string | Yes | Stable graph-node id, future:<code>:<resourceUuid>. |
futureEvents[].rebillSequence | integer or null | Yes | The next chronological rebill sequence for subscription.rebill, or null for every other future event. Minimum: 1. |
futureEvents[].resourceUuid | string | Yes | The subscription this event is scheduled against: the same uuid as its subscription event in events, so the dashboard can anchor the projection to the node it belongs to. |
futureEvents[].title | string | Yes | Short human label: the subscription plan name. |
lastEventAt | string (date-time) or null | Yes | Timestamp of the newest event, or null when the timeline is empty. |
userEmail | string or null | Yes | The user email, or null when the user row is not resolvable. |
userFirstName | string or null | Yes | The user first name (empty string when the user is unnamed), or null when the user row is not resolvable. |
userLastName | string or null | Yes | The user last name (empty string when the user is unnamed), or null when the user row is not resolvable. |
userUuid | string | Yes | The Flopay user UUID this timeline belongs to. |
Errors
| Status | Description |
|---|---|
400 | The list query parameters were invalid, or record was called without a valid userUuid. |
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 timeline exists for the supplied user under the authenticated client. |
User_exportUsers
Export users
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/users/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 |
|---|---|---|---|---|
id | query | string | No | 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. |
email | query | string | No | User email address. Equality filter. Pass without operator for exact match or pass any of the following operators: [search]. [search] is case-insensitive text contains matching. |
clientUserId | query | string | No | Client-managed user identifier (user.client_user_id). 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. |
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, email, updatedAt. Default: createdAt DESC. Allowed values: createdAt, email, updatedAt. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
createdAt | query | string (date-time) | No | User creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
updatedAt | query | string (date-time) | No | User update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
uuid | query | string | No | 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. |
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. |
424 | The downstream billing provider could not be reached or returned an unexpected error. |
429 | Export capacity exhausted. Retry-After is set to 60 seconds. |
503 | Exports disabled or export storage unavailable. |
User_getUserById
Get User By ID
Returns the user details for the supplied user id. The user must belong to the authenticated client.
| Policy | Value |
|---|---|
| Operation | GET /v1/users/{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 (uuid) | Yes | The Flopay user UUID scoped to the authenticated client. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
Result
Returns 200 with a JSON body. The user details for the requested user id.
| Field | Type | Required | Description |
|---|---|---|---|
address | object or null | Yes | The billing address for the user when available. Default: null. |
address.city | string or null | Yes | The billing city. |
address.country | string or null | Yes | The billing country code or name. |
address.geoCode | string or null | Yes | The GeoIP or provider geocode when available. |
address.phone | string or null | Yes | The billing phone number. |
address.postalCode | string or null | Yes | The billing postal code. |
address.region | string or null | Yes | The billing region or state. |
address.street1 | string or null | Yes | The first address line. |
businessDetails | object or null | No | The buyer's business details at the authenticated merchant (customerType, legalName, address, taxId), set with PATCH /v1/users/{id}/business-details or at checkout. null when the buyer has none at this merchant. Returned by GET /v1/users/{id}. |
email | string | Yes | The current email address for the user. |
firstName | string | Yes | The user first name when available from the billing provider. |
id | string | Yes | The API user identifier. Use this value in /v1/users/{id} routes. |
lastName | string | Yes | The user last name when available from the billing provider. |
providerCode | string | Yes | A provider-specific code or internal user reference when available. |
Errors
| Status | Description |
|---|---|
400 | The request body, path parameters, or query parameters 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. |
403 | The caller lacks the required read scope, or its live merchant membership is inactive or no longer authorizes the request. |
404 | No user with the supplied id exists for the authenticated client. |
424 | The downstream billing provider could not be reached or returned an unexpected error. |
User_getUserPurchases
Get User Purchases
Returns the product codes already purchased by the supplied user. If the optional ids query parameter is provided, the response only includes matches from that list.
| Policy | Value |
|---|---|
| Operation | GET /v1/users/{id}/purchases |
| 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 (uuid) | Yes | The Flopay user UUID scoped to the authenticated client. |
ids | query | string | No | Optional comma-separated list of product codes to filter against. When omitted, all purchased product codes are returned. |
Result
Returns 200 with a JSON body. A list of purchased product codes for the requested user.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of string | Yes | Product codes the user has already purchased. |
Errors
| Status | Description |
|---|---|
400 | The request body, path parameters, or query parameters 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. |
403 | The caller lacks the required read scope, or its live merchant membership is inactive or no longer authorizes the request. |
404 | No user with the supplied id exists for the authenticated client. |
424 | The downstream billing provider could not be reached or returned an unexpected error. |
User_getUserSubscriptions
Get User Subscriptions
Returns the subscription rows stored in the Flopay subscription table for the supplied user id. The user must belong to the authenticated client.
| Policy | Value |
|---|---|
| Operation | GET /v1/users/{id}/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 |
|---|---|---|---|---|
id | path | string (uuid) | Yes | The Flopay user UUID scoped to the authenticated client. |
Result
Returns 200 with a JSON body. A list of stored subscription records for the requested user.
| 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 request body, path parameters, or query parameters 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. |
403 | The caller lacks the required read scope, or its live merchant membership is inactive or no longer authorizes the request. |
404 | No user with the supplied id exists for the authenticated client. |
424 | The downstream billing provider could not be reached or returned an unexpected error. |
User_listUsers
List Users
Returns a paginated list of locally persisted users for the authenticated client. Supports page, limit, sort[asc|desc], optional email, clientUserId, and id (Flopay user UUID) exact-match convenience filters, and bracket-operator filters on the USER_LIST_QUERY_CONFIG whitelist. Passing email=, clientUserId=, or id= narrows the list to the matching user (an empty data array when nothing matches); the response shape is unchanged. The id filter lets a caller holding either identifier resolve a user through one contract: clientUserId is client-managed and optional, so it may never have been set for a given user.
| Policy | Value |
|---|---|
| Operation | GET /v1/users |
| 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 | query | string | No | 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. |
email | query | string | No | User email address. Equality filter. Pass without operator for exact match or pass any of the following operators: [search]. [search] is case-insensitive text contains matching. |
clientUserId | query | string | No | Client-managed user identifier (user.client_user_id). 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. |
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, email, updatedAt. Default: createdAt DESC. Allowed values: createdAt, email, updatedAt. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
createdAt | query | string (date-time) | No | User creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
updatedAt | query | string (date-time) | No | User update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
uuid | query | string | No | 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. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].clientUserId | string or null | No | |
data[].createdAt | string (date-time) | Yes | |
data[].email | string | Yes | |
data[].firstName | string | Yes | |
data[].id | string | Yes | |
data[].lastName | string | Yes | |
data[].updatedAt | string (date-time) | Yes | |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The request body, path parameters, or query parameters 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. |
403 | The caller lacks the required read scope, or its live merchant membership is inactive or no longer authorizes the request. |
424 | The downstream billing provider could not be reached or returned an unexpected error. |
User_lookup
Resolve or disambiguate a customer
Resolves an exact tenant-linked Flo UUID first, then an exact merchant clientUserId. Otherwise returns every bounded, paginated email-or-name candidate and never silently selects one. Candidate fields are the existing authenticated local-user DTO only; no payment provider is called.
| Policy | Value |
|---|---|
| Operation | GET /v1/users/lookup |
| 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 |
|---|---|---|---|---|
value | query | string | Yes | Flo UUID, merchant clientUserId, email, or customer name. Exact stable identifiers are resolved before email/name candidates. Maximum length: 300. |
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: 50. |
sort | query | string | No | Sort by one allowed field. Use exactly one of sort[asc] or sort[desc]. Allowed fields: createdAt, email, updatedAt. Default: createdAt DESC. Allowed values: createdAt, email, updatedAt. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
Result
Returns 200 with a JSON body. An exact stable-identifier match, explicit email/name candidates, or an empty result.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].clientUserId | string or null | No | |
data[].createdAt | string (date-time) | Yes | |
data[].email | string | Yes | |
data[].firstName | string | Yes | |
data[].id | string | Yes | |
data[].lastName | string | Yes | |
data[].updatedAt | string (date-time) | Yes | |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
resolution | object | Yes | |
resolution.kind | string | Yes | Allowed values: exact, candidates, none. |
resolution.matchedBy | string or null | Yes | Allowed values: flo-uuid, client-user-id, email-or-name. |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The request body, path parameters, or query parameters 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. |
403 | The caller lacks the required read scope, or its live merchant membership is inactive or no longer authorizes the request. |
424 | The downstream billing provider could not be reached or returned an unexpected error. |
User_merge
Merge Users
Merges the source user named in the body into the target user in the path, for the authenticated merchant only. Both users must be linked to the merchant. The merchant's link, provider customers, saved payment methods, subscriptions, payments, checkout sessions, invoices and disputes of the source move to the target; rows the source has at other merchants stay where they are. Identical saved cards are deduplicated first. When either user is shared with another merchant, the global email and names stay untouched. The source user is deleted once nothing else references it, and kept while another merchant still links it. The merge is irreversible. Requires an Idempotency-Key: repeating a completed merge with the same key and body returns the original response without merging again. Preview it first with POST /v1/users/{id}/merge/preview.
| Policy | Value |
|---|---|
| Operation | POST /v1/users/{id}/merge |
| Class | mutating |
| Risk | critical |
| Confirmation | required |
| Retry | manual-reconciliation |
| Rate-limit tier | restricted |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | Yes | The Flopay user UUID scoped to the authenticated client. |
keepClientUserId | body | string | No | The client_user_id to keep on the target link when both users carry a different one at the authenticated merchant. It must be one of the two existing ids. Maximum length: 100. |
sourceUserUuid | body | string (uuid) | Yes | The duplicate user whose rows at the authenticated merchant move to the target user in the path. It must be linked to the authenticated merchant. |
Result
Returns 200 with a JSON body. The merge committed.
| Field | Type | Required | Description |
|---|---|---|---|
movedRows | array of object | Yes | The authenticated merchant's rows that moved to the target, per table. |
movedRows[].ids | array of string | Yes | The ids of the rows that now reference the target user. |
movedRows[].table | string | Yes | The table the rows were moved in. |
operationId | string (uuid) | Yes | The durable merge operation id. |
providerSync | object | Yes | |
providerSync.status | string | Yes | Whether the payment-provider customer metadata was updated after the merge committed. A failure never undoes the merge. Allowed values: succeeded, failed. |
status | string | Yes | The merge operation status. Allowed values: completed. |
targetUserId | string (uuid) | Yes | The target user every moved row now references. |
Errors
| Status | Description |
|---|---|
400 | The request body or path is malformed, or the Idempotency-Key header is missing or blank. |
401 | Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use client.uuid as the username and a current client-scoped API token as the password; for bearer, send a valid OAuth2 access token with the required scope. |
403 | The caller lacks the required scope, or its live merchant membership is not an owner or admin. Only merchant owners and admins can merge customers. |
404 | merge_user_not_found, with party (source or target): the user does not exist or is not linked to the authenticated merchant. Both cases answer identically. |
409 | Nothing was merged. merge_unscopable_table, with tables: the source has rows that cannot be limited to one merchant. merge_in_flight_payment_method_use_claim, merge_in_flight_payment_operation, merge_in_flight_renewal_attempt, merge_in_flight_card_deletion, merge_in_flight_checkout_attempt, merge_in_flight_scheduled_cancellation, with party: work is in flight for that user; retry once it has finished. merge_duplicate_payment_method_in_use: both users hold the same card and both copies are in use. merge_operation_open_for_other_target: the source has an open merge into another user. merge_idempotency_key_reused: the key was used for a different request. merge_idempotency_key_in_progress: a merge with this key is still running. |
422 | merge_client_user_id_choice_required: both users carry a different client_user_id at this merchant and the body names none to keep. merge_client_user_id_choice_invalid: keepClientUserId is neither existing id. merge_source_is_target: the source and the target are the same user. |
503 | merge_dedupe_deletion_incomplete or merge_dedupe_provider_default_unverifiable: a duplicate card could not be removed or checked yet. Retry the merge with the same key. |
User_updateUser
Update User Email
Updates the email address for the supplied user id. The path user id must belong to the authenticated client. Only the new email address is required in the request body. Rejected with 403 Forbidden when the user is linked to another client; once a user is shared across clients, email updates must move through a future verified user-owned flow.
| Policy | Value |
|---|---|
| Operation | PATCH /v1/users/{id} |
| Class | mutating |
| Risk | medium |
| Confirmation | required |
| Retry | manual-reconciliation |
| Rate-limit tier | mutation |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | Yes | The Flopay user UUID scoped to the authenticated client. |
email | body | string (email) | Yes | The new email address to assign to the user. |
Result
Returns 204 with no body. The user email was updated successfully. The response body is empty.
Errors
| Status | Description |
|---|---|
400 | The request body, path parameters, or query parameters 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. |
403 | The caller lacks the required read scope, or its live merchant membership is inactive or no longer authorizes the request. |
404 | No user with the supplied id exists for the authenticated client. |
424 | The downstream billing provider could not be reached or returned an unexpected error. |
UserPurchaseRecords_list
List User Purchase Records
Returns authoritative payment records from the local transaction table for one Flopay user within the authenticated merchant. The path user and merchant tenant are mandatory scopes applied before the shared payment filters. No payment provider is queried. A user outside the merchant boundary returns 404; a known user with no matching records returns an empty paginated list.
| Policy | Value |
|---|---|
| Operation | GET /v1/users/{id}/purchase-records |
| 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 | query | string | No | Payment identifier. 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. |
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: amount, createdAt, floFeeUsd, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency, gateway.sessionMode, subscription.uuid, subscription.gatewayType, subscription.gatewaySubscriptionId, subscription.planId, subscription.planName, subscription.quantity, subscription.rebillCount, subscription.currency, subscription.amount, subscription.total, subscription.state, subscription.startDate, subscription.endDate, subscription.canceledAt, subscription.createdAt, subscription.updatedAt. Default: createdAt DESC. Allowed values: amount, createdAt, floFeeUsd, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency, gateway.sessionMode, subscription.uuid, subscription.gatewayType, subscription.gatewaySubscriptionId, subscription.planId, subscription.planName, subscription.quantity, subscription.rebillCount, subscription.currency, subscription.amount, subscription.total, subscription.state, subscription.startDate, subscription.endDate, subscription.canceledAt, subscription.createdAt, subscription.updatedAt. |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: gateway, subscription. Unknown aliases return 400. |
amount | query | number | No | Payment amount. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
currency | query | string | No | Payment currency. 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. |
description | query | string | No | Payment description. Equality filter. Pass without operator for exact match or pass any of the following operators: [search]. [search] is case-insensitive text contains matching. |
email | query | string | No | Email address of the user linked to the payment. Equality filter. Pass without operator for exact match or pass any of the following operators: [search]. [search] is case-insensitive text contains matching. |
floFeeUsd | query | number | No | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
occurredAt | query | string (date-time) | No | Payment occurrence timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
provider | query | string | No | Payment provider. 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. |
status | query | string | No | Canonical payment lifecycle 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: pending, authorized, processing, succeeded, failed, refunded, partially_refunded, refund_failed, voided, reversed, unknown. |
type | query | string | No | Financial event type. 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: purchase, refund, chargeback, dispute. |
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. |
id | path | any | Yes | Stable Flopay user UUID scoped to the authenticated merchant. |
Result
Returns 200 with a JSON body. A tenant- and user-scoped page of locally persisted payment records with authoritative Flopay transaction ids.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].amount | number | Yes | |
data[].authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
data[].authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
data[].checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].checkoutSessionId | string or null | No | Originating checkout session UUID. |
data[].createdAt | string (date-time) | Yes | Record creation timestamp. |
data[].currency | string | Yes | |
data[].description | string or null | Yes | |
data[].effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
data[].financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
data[].floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
data[].floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
data[].gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
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[].gatewayChargeId | string or null | No | Original gateway charge identifier. |
data[].gatewayPaymentIntentId | string or null | No | Opaque provider payment-object identifier, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility. |
data[].gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
data[].gatewayTransactionId | string or null | No | Gateway transaction identifier. |
data[].id | string | Yes | |
data[].metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
data[].occurredAt | string (date-time) | Yes | |
data[].refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
data[].refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
data[].refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
data[].refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
data[].status | string | Yes | |
data[].subscription | object | No | Linked subscription (non-secret fields incl. metadata). Present only when the subscription relation is loaded and the payment is tied to a subscription. |
data[].subscription.amount | number or null | Yes | The stored single-unit amount. |
data[].subscription.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[].subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
data[].subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
data[].subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
data[].subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
data[].subscription.createdAt | string (date-time) | Yes | When the row was created. |
data[].subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
data[].subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
data[].subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
data[].subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
data[].subscription.gateway.id | string | Yes | Gateway UUID. |
data[].subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].subscription.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[].subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
data[].subscription.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[].subscription.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[].subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
data[].subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
data[].subscription.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[].subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
data[].subscription.meteredItems[].name | string | Yes | |
data[].subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
data[].subscription.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[].subscription.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[].subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
data[].subscription.planDescription | string or null | Yes | The stored plan description when available. |
data[].subscription.planId | string | Yes | The stored plan identifier. |
data[].subscription.planName | string | Yes | The stored plan name. |
data[].subscription.quantity | number | Yes | The subscribed quantity. |
data[].subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
data[].subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
data[].subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
data[].subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
data[].subscription.total | number or null | Yes | The stored total amount. |
data[].subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
data[].subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
data[].subscription.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[].subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
data[].subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
data[].subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
data[].subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
data[].subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
data[].subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
data[].type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
data[].userEmail | string or null | No | Customer email when the user relation is loaded. |
data[].userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].userUuid | string or null | No | Linked Flopay user UUID. |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The user id or list query parameters were invalid. |
401 | A valid client API key or OAuth2 bearer token is required. |
403 | The authenticated principal lacks merchant read access. |
404 | No user with the requested id belongs to the authenticated merchant. |
Transactions tools
Arguments, results, errors, and access, confirmation, and retry policy for each Transactions tool in FloPay MCP, from the reviewed API contract.
Webhooks tools
Arguments, results, errors, and access, confirmation, and retry policy for each Webhooks tool in FloPay MCP, from the reviewed API contract.