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 764b41d5c7205d6df7eeaeac832fafe882247f5526b1d4d6bc6f98e3eaca7784.
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[].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[].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[].id | string | Yes | The Flopay invoice UUID. |
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.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.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.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.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.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.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.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_list
List Payment Methods
Returns paginated saved payment methods for the authenticated client. Only methods whose owning gateway belongs 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. The response exposes display fields only: vault tokens, provider payment method ids, 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 |
|---|---|---|---|---|
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 | Stored payment method type (card or PayPal). 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. |
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[].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[].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[].id | string | Yes | Flopay payment method UUID. |
data[].lastFour | string or null | No | Last four digits of the card. Null for non-card types. |
data[].payerEmail | string or null | No | Payer email for wallet types (PayPal). Null for cards. |
data[].status | string | Yes | Payment method lifecycle status. Allowed values: pending, active, deleted. |
data[].type | string | Yes | Stored payment method type. Allowed values: card, paypal. |
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. |
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. |
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. |
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. |
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. |
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[].cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
data[].canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
data[].checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
data[].clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
data[].createdAt | string (date-time) | Yes | When the row was created. |
data[].currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
data[].endDate | string (date-time) or null | Yes | When the current subscription term ends. |
data[].gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
data[].gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].gateway.environment | string | Yes | Allowed values: stage, production. |
data[].gateway.id | string | Yes | Gateway UUID. |
data[].gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
data[].gatewaySubscriptionId | string | Yes | The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized flo_<uuid> identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway. |
data[].gatewayType | string | Yes | The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read ownership to tell the two apart. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
data[].metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
data[].ownership | string | Yes | Who owns the billing schedule. provider means the gateway holds the subscription object and drives renewals; flo means Flopay holds the schedule and drives renewals itself, charging through the gateway named by gatewayType. Allowed values: flo, provider. |
data[].pauseState | string or null | Yes | Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: scheduled, active. |
data[].pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
data[].planDescription | string or null | Yes | The stored plan description when available. |
data[].planId | string | Yes | The stored plan identifier. |
data[].planName | string | Yes | The stored plan name. |
data[].quantity | number | Yes | The subscribed quantity. |
data[].rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
data[].resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
data[].startDate | string (date-time) or null | Yes | When the subscription started. |
data[].state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
data[].total | number or null | Yes | The stored total amount. |
data[].trialEnd | string (date-time) or null | Yes | When the trial ends. |
data[].updatedAt | string (date-time) | Yes | When the row was last updated. |
data[].userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
data[].userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
data[].uuid | string | Yes | Internal Flopay subscription UUID. |
Errors
| Status | Description |
|---|---|
400 | The 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_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, 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, 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, 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[].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[].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[].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.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.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.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.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.