MCPTool reference
Webhooks tools
Arguments, results, errors, and access, confirmation, and retry policy for each Webhooks tool in FloPay MCP, from the reviewed API contract.
Webhooks tools
Generated from the FloPay MCP contract version 1, revision 764b41d5c7205d6df7eeaeac832fafe882247f5526b1d4d6bc6f98e3eaca7784.
ClientWebhook_list
List Webhooks
Lists webhook endpoints configured for the authenticated client. Supports page, limit, sort[asc|desc], no relation aliases, and whitelisted filters for id, url, createdAt, updatedAt, failedSendAt, and disabledAt. Invalid list parameters return 400.
| Policy | Value |
|---|---|
| Operation | GET /v1/webhooks |
| 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, disabledAt, failedSendAt, updatedAt, url. Default: createdAt DESC. Allowed values: createdAt, disabledAt, failedSendAt, updatedAt, url. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
createdAt | query | string (date-time) | No | Webhook endpoint creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
disabledAt | query | string (date-time) | No | Webhook endpoint disabled timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
failedSendAt | query | string (date-time) | No | Webhook endpoint last failed delivery timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
id | query | string | No | Webhook endpoint id. 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. |
updatedAt | query | string (date-time) | No | Webhook endpoint update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
url | query | string | No | Webhook endpoint URL. Equality filter. Pass without operator for exact match or pass any of the following operators: [search]. [search] is case-insensitive text contains matching. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].clientId | string | Yes | Owning client UUID. |
data[].createdAt | string (date-time) | Yes | |
data[].disabledAt | string (date-time) or null | Yes | |
data[].events | array of string | Yes | |
data[].failedSendAt | string (date-time) or null | Yes | |
data[].filter | object or null | Yes | Optional product filter. At least one associated product must match every populated selector set. Null delivers every subscribed event. |
data[].filter.productIds | array of string (uuid) | No | Up to 50 active product UUIDs owned by the authenticated client. Maximum items: 50. |
data[].filter.productTags | array of string | No | Up to 50 exact, case-sensitive tags present on active products owned by the client. Maximum items: 50. |
data[].id | string | Yes | |
data[].signingSecret | string | Yes | Secret used to sign outbound webhook deliveries with the Flo-Signature header. |
data[].updatedAt | string (date-time) | Yes | |
data[].url | string | Yes | |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
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. |
ClientWebhookEvent_exportEvents
Export webhook-events
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/webhooks/events/exports |
| Class | read-only |
| Risk | medium |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | aggregate |
| Roles | owner, admin |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
page | query | integer | No | 1-based page number for paginated list endpoints. Default: 1. Minimum: 1. |
limit | query | integer | No | Maximum number of records to return per page. Default: 20. Minimum: 1. Maximum: 100. |
sort | query | string | No | Sort by one allowed field. Use exactly one of sort[asc] or sort[desc]. Allowed fields: createdAt, eventType, retryCount, sentAt, skipReason, status, updatedAt, invoice.id, invoice.gatewayInvoiceId, invoice.gatewayType, invoice.state, invoice.billingReason, invoice.transactionType, invoice.currency, invoice.total, invoice.userUuid, invoice.transactionUuid, invoice.paidAt, invoice.createdAt, invoice.updatedAt, original.id, original.eventType, original.status, original.retryCount, original.gatewayEventId, original.responseCode, original.sentAt, original.originalUuid, original.userUuid, original.transactionUuid, original.subscriptionUuid, original.invoiceUuid, original.createdAt, original.updatedAt, 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, transaction.id, transaction.amount, transaction.currency, transaction.status, transaction.description, transaction.createdAt, transaction.userUuid, transaction.checkoutSessionId, transaction.subscriptionUuid, transaction.gatewayTransactionId, transaction.gatewayPaymentIntentId, user.id, user.email, user.firstName, user.lastName, user.createdAt, user.updatedAt, webhook.id, webhook.clientId, webhook.url, webhook.failedSendAt, webhook.disabledAt, webhook.createdAt, webhook.updatedAt. Default: createdAt DESC. Allowed values: createdAt, eventType, retryCount, sentAt, skipReason, status, updatedAt, invoice.id, invoice.gatewayInvoiceId, invoice.gatewayType, invoice.state, invoice.billingReason, invoice.transactionType, invoice.currency, invoice.total, invoice.userUuid, invoice.transactionUuid, invoice.paidAt, invoice.createdAt, invoice.updatedAt, original.id, original.eventType, original.status, original.retryCount, original.gatewayEventId, original.responseCode, original.sentAt, original.originalUuid, original.userUuid, original.transactionUuid, original.subscriptionUuid, original.invoiceUuid, original.createdAt, original.updatedAt, 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, transaction.id, transaction.amount, transaction.currency, transaction.status, transaction.description, transaction.createdAt, transaction.userUuid, transaction.checkoutSessionId, transaction.subscriptionUuid, transaction.gatewayTransactionId, transaction.gatewayPaymentIntentId, user.id, user.email, user.firstName, user.lastName, user.createdAt, user.updatedAt, webhook.id, webhook.clientId, webhook.url, webhook.failedSendAt, webhook.disabledAt, webhook.createdAt, webhook.updatedAt. |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: invoice, original, subscription, transaction, user, webhook. Unknown aliases return 400. |
createdAt | query | string (date-time) | No | Webhook delivery creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
eventType | query | string | No | Flo webhook 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: dispute.created, dispute.updated, dispute.won, dispute.lost, pre_dispute_alert.created, pre_dispute_alert.updated, subscription.created, subscription.updated, subscription.cancelled, subscription.renewed, subscription.reactivated, subscription.paused, subscription.resumed, subscription.expired, item.purchased, item.refunded, item.charged_back, invoice.created, invoice.deleted, invoice.updated, invoice.payment_failed, invoice.paid, invoice.overdue, payment.authorized, payment.capture_failed, payment.authorization_voided, payment.authorization_expired. |
disputeUuid | query | string | No | Flo dispute this event relates to. 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. |
gatewayEventId | query | string | No | Provider event 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. |
id | query | string | No | Webhook delivery id. 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. |
invoiceUuid | query | string | No | Flo invoice this event relates to. 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. |
originalUuid | query | string | No | Original webhook delivery id for resend attempts. 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. |
preDisputeAlertUuid | query | string | No | Flo Pre-Dispute Alert this event relates to. 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. |
responseCode | query | string | No | Last client response code. 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. |
retryCount | query | number | No | Delivery retry count. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
sentAt | query | string (date-time) | No | Webhook delivery sent timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
skipReason | query | string | No | Intentional webhook delivery exclusion reason. 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: endpoint_disabled, event_not_subscribed, endpoint_created_after_event, filter_context_missing, filter_not_matched. |
status | query | string | No | Webhook delivery 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, success, failed, retrying, skipped. |
subscriptionUuid | query | string | No | Flo subscription this event relates to. 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. |
transactionUuid | query | string | No | Flo transaction this event relates to. 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. |
updatedAt | query | string (date-time) | No | Webhook delivery 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 | Flo user this event relates to. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. |
fields | body | array of string | No | Stable export field keys in output order. |
format | body | string | Yes | Allowed values: csv, json. |
scope | body | string | Yes | Allowed values: current_page, all_matching. |
Result
Returns 200 as application/vnd.flopay.export-stream.v1. Versioned length-prefixed export stream containing started/progress/completed_file/file_chunk/complete frames.
Errors
| Status | Description |
|---|---|
400 | Invalid scope, format, field key, query parameter, client selector, row cap, or plaintext byte cap. |
401 | Authentication is missing or invalid. |
403 | The actor is not allowed to export this resource. |
429 | Export capacity exhausted. Retry-After is set to 60 seconds. |
503 | Exports disabled or export storage unavailable. |
ClientWebhookEvent_findOne
Get Webhook Event
Returns a single webhook delivery attempt for the authenticated client. 404 when the event id does not belong to one of the client’s webhooks.
| Policy | Value |
|---|---|
| Operation | GET /v1/webhooks/events/{id} |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
createdAt | string (date-time) | Yes | |
disputeUuid | string or null | No | Flo dispute this event relates to, when resolvable. |
eventType | string | Yes | |
gatewayEventId | string or null | No | |
id | string | Yes | |
invoice | object or null | No | Related invoice. Present only when requested with relation=invoice. |
invoice.billingReason | string or null | No | Provider-reported billing reason. |
invoice.createdAt | string (date-time) | Yes | When the invoice was created. |
invoice.currency | string or null | No | |
invoice.gateway | object or null | No | Owning gateway (non-secret fields). Present when the gateway relation is loaded. |
invoice.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
invoice.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
invoice.gateway.environment | string | Yes | Allowed values: stage, production. |
invoice.gateway.id | string | Yes | Gateway UUID. |
invoice.gateway.name | string | Yes | Human-readable name of the gateway account. |
invoice.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
invoice.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
invoice.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. |
invoice.gatewayType | string | Yes | The billing provider that produced this invoice. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
invoice.id | string | Yes | The Flopay invoice UUID. |
invoice.paidAt | string (date-time) or null | No | When the invoice was paid by the provider. |
invoice.state | string | Yes | The current invoice state. Allowed values: open, pending, processing, pastDue, paid, closed, failed, voided, unknown. |
invoice.total | number or null | No | |
invoice.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. |
invoice.transaction.amount | number | Yes | |
invoice.transaction.authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
invoice.transaction.authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
invoice.transaction.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
invoice.transaction.checkoutSessionId | string or null | No | Originating checkout session UUID. |
invoice.transaction.createdAt | string (date-time) | Yes | Record creation timestamp. |
invoice.transaction.currency | string | Yes | |
invoice.transaction.description | string or null | Yes | |
invoice.transaction.effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
invoice.transaction.financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
invoice.transaction.floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
invoice.transaction.floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
invoice.transaction.gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
invoice.transaction.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
invoice.transaction.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
invoice.transaction.gateway.environment | string | Yes | Allowed values: stage, production. |
invoice.transaction.gateway.id | string | Yes | Gateway UUID. |
invoice.transaction.gateway.name | string | Yes | Human-readable name of the gateway account. |
invoice.transaction.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
invoice.transaction.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
invoice.transaction.gatewayChargeId | string or null | No | Original gateway charge identifier. |
invoice.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. |
invoice.transaction.gatewayTransactionId | string or null | No | Gateway transaction identifier. |
invoice.transaction.id | string | Yes | |
invoice.transaction.metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
invoice.transaction.occurredAt | string (date-time) | Yes | |
invoice.transaction.status | string | Yes | |
invoice.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. |
invoice.transaction.subscription.amount | number or null | Yes | The stored single-unit amount. |
invoice.transaction.subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
invoice.transaction.subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
invoice.transaction.subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
invoice.transaction.subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
invoice.transaction.subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
invoice.transaction.subscription.createdAt | string (date-time) | Yes | When the row was created. |
invoice.transaction.subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
invoice.transaction.subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
invoice.transaction.subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
invoice.transaction.subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
invoice.transaction.subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
invoice.transaction.subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
invoice.transaction.subscription.gateway.id | string | Yes | Gateway UUID. |
invoice.transaction.subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
invoice.transaction.subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
invoice.transaction.subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
invoice.transaction.subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
invoice.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. |
invoice.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. |
invoice.transaction.subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
invoice.transaction.subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
invoice.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. |
invoice.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. |
invoice.transaction.subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
invoice.transaction.subscription.planDescription | string or null | Yes | The stored plan description when available. |
invoice.transaction.subscription.planId | string | Yes | The stored plan identifier. |
invoice.transaction.subscription.planName | string | Yes | The stored plan name. |
invoice.transaction.subscription.quantity | number | Yes | The subscribed quantity. |
invoice.transaction.subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
invoice.transaction.subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
invoice.transaction.subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
invoice.transaction.subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
invoice.transaction.subscription.total | number or null | Yes | The stored total amount. |
invoice.transaction.subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
invoice.transaction.subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
invoice.transaction.subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
invoice.transaction.subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
invoice.transaction.subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
invoice.transaction.subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
invoice.transaction.subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
invoice.transaction.subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
invoice.transaction.type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
invoice.transaction.userEmail | string or null | No | Customer email when the user relation is loaded. |
invoice.transaction.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
invoice.transaction.userLastName | string or null | No | Customer last name when the user relation is loaded. |
invoice.transaction.userUuid | string or null | No | Linked Flopay user UUID. |
invoice.transactionType | string or null | No | Provider-reported transaction type. |
invoice.transactionUuid | string or null | No | Linked Flopay transaction UUID. |
invoice.updatedAt | string (date-time) | Yes | When the invoice was last updated. |
invoice.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
invoice.userLastName | string or null | No | Customer last name when the user relation is loaded. |
invoice.userUuid | string or null | No | Linked Flopay user UUID. |
invoiceUuid | string or null | No | Flo invoice this event relates to, when resolvable. |
original | object or null | No | Original delivery record. Present only when requested with relation=original. |
originalUuid | string or null | No | |
preDisputeAlertUuid | string or null | No | Flo Pre-Dispute Alert this event relates to, when Flo retains the alert. |
requestBody | object | Yes | The Flo webhook payload that will be POSTed to the client. |
responseBody | object or null | No | The last response body returned by the client endpoint. |
responseCode | string or null | No | |
retryCount | number | Yes | |
sentAt | string (date-time) or null | No | |
skipReason | string or null | No | Machine-readable reason an event was intentionally excluded before any delivery attempt. Allowed values: endpoint_disabled, event_not_subscribed, endpoint_created_after_event, filter_context_missing, filter_not_matched. |
source | string or null | No | Allowed values: STRIPE, PAYPAL, WORLDPAY_CORPORATE_GATEWAY, CHARGEBACK. |
status | string | Yes | Allowed values: pending, success, failed, retrying, skipped. |
subscription | object or null | No | Related subscription. Present only when requested with relation=subscription. |
subscription.amount | number or null | Yes | The stored single-unit amount. |
subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
subscription.createdAt | string (date-time) | Yes | When the row was created. |
subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
subscription.gateway.id | string | Yes | Gateway UUID. |
subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
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. |
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. |
subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
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. |
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. |
subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
subscription.planDescription | string or null | Yes | The stored plan description when available. |
subscription.planId | string | Yes | The stored plan identifier. |
subscription.planName | string | Yes | The stored plan name. |
subscription.quantity | number | Yes | The subscribed quantity. |
subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
subscription.total | number or null | Yes | The stored total amount. |
subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
subscriptionUuid | string or null | No | Flo subscription this event relates to, when resolvable. |
transaction | object or null | No | Related payment. Present only when requested with relation=transaction. |
transaction.amount | number | Yes | |
transaction.authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
transaction.authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
transaction.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
transaction.checkoutSessionId | string or null | No | Originating checkout session UUID. |
transaction.createdAt | string (date-time) | Yes | Record creation timestamp. |
transaction.currency | string | Yes | |
transaction.description | string or null | Yes | |
transaction.effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
transaction.financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
transaction.floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
transaction.floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
transaction.gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
transaction.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
transaction.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
transaction.gateway.environment | string | Yes | Allowed values: stage, production. |
transaction.gateway.id | string | Yes | Gateway UUID. |
transaction.gateway.name | string | Yes | Human-readable name of the gateway account. |
transaction.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
transaction.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
transaction.gatewayChargeId | string or null | No | Original gateway charge identifier. |
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. |
transaction.gatewayTransactionId | string or null | No | Gateway transaction identifier. |
transaction.id | string | Yes | |
transaction.metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
transaction.occurredAt | string (date-time) | Yes | |
transaction.status | string | Yes | |
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. |
transaction.subscription.amount | number or null | Yes | The stored single-unit amount. |
transaction.subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
transaction.subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
transaction.subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
transaction.subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
transaction.subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
transaction.subscription.createdAt | string (date-time) | Yes | When the row was created. |
transaction.subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
transaction.subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
transaction.subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
transaction.subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
transaction.subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
transaction.subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
transaction.subscription.gateway.id | string | Yes | Gateway UUID. |
transaction.subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
transaction.subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
transaction.subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
transaction.subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
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. |
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. |
transaction.subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
transaction.subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
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. |
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. |
transaction.subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
transaction.subscription.planDescription | string or null | Yes | The stored plan description when available. |
transaction.subscription.planId | string | Yes | The stored plan identifier. |
transaction.subscription.planName | string | Yes | The stored plan name. |
transaction.subscription.quantity | number | Yes | The subscribed quantity. |
transaction.subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
transaction.subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
transaction.subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
transaction.subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
transaction.subscription.total | number or null | Yes | The stored total amount. |
transaction.subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
transaction.subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
transaction.subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
transaction.subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
transaction.subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
transaction.subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
transaction.subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
transaction.subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
transaction.type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
transaction.userEmail | string or null | No | Customer email when the user relation is loaded. |
transaction.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
transaction.userLastName | string or null | No | Customer last name when the user relation is loaded. |
transaction.userUuid | string or null | No | Linked Flopay user UUID. |
transactionUuid | string or null | No | Flo transaction this event relates to, when resolvable. |
updatedAt | string (date-time) | Yes | |
user | object or null | No | Related user. Present only when requested with relation=user. |
user.clientUserId | string or null | No | |
user.createdAt | string (date-time) | Yes | |
user.email | string | Yes | |
user.firstName | string | Yes | |
user.id | string | Yes | |
user.lastName | string | Yes | |
user.updatedAt | string (date-time) | Yes | |
userUuid | string or null | No | Flo user this event relates to, when resolvable. |
webhook | object | No | Parent webhook endpoint. Present only when requested with relation=webhook. |
webhook.clientId | string | Yes | |
webhook.createdAt | string (date-time) | Yes | |
webhook.disabledAt | string (date-time) or null | No | |
webhook.events | array of string | Yes | |
webhook.failedSendAt | string (date-time) or null | No | |
webhook.id | string | Yes | |
webhook.updatedAt | string (date-time) | Yes | |
webhook.url | string | Yes |
Errors
| Status | Description |
|---|---|
400 | The supplied path or list query is 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 webhook event with the requested id exists for this client. |
ClientWebhookEvent_list
List Webhook Events
Lists every endpoint delivery decision owned by the authenticated client. Filter exclusions are terminal skipped rows with skipReason set to filter_not_matched or filter_context_missing, zero attempts, and no delivery failure. Supports page, limit, sort[asc|desc], and whitelisted filters including skipReason.
| Policy | Value |
|---|---|
| Operation | GET /v1/webhooks/events |
| 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, eventType, retryCount, sentAt, skipReason, status, updatedAt, invoice.id, invoice.gatewayInvoiceId, invoice.gatewayType, invoice.state, invoice.billingReason, invoice.transactionType, invoice.currency, invoice.total, invoice.userUuid, invoice.transactionUuid, invoice.paidAt, invoice.createdAt, invoice.updatedAt, original.id, original.eventType, original.status, original.retryCount, original.gatewayEventId, original.responseCode, original.sentAt, original.originalUuid, original.userUuid, original.transactionUuid, original.subscriptionUuid, original.invoiceUuid, original.createdAt, original.updatedAt, 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, transaction.id, transaction.amount, transaction.currency, transaction.status, transaction.description, transaction.createdAt, transaction.userUuid, transaction.checkoutSessionId, transaction.subscriptionUuid, transaction.gatewayTransactionId, transaction.gatewayPaymentIntentId, user.id, user.email, user.firstName, user.lastName, user.createdAt, user.updatedAt, webhook.id, webhook.clientId, webhook.url, webhook.failedSendAt, webhook.disabledAt, webhook.createdAt, webhook.updatedAt. Default: createdAt DESC. Allowed values: createdAt, eventType, retryCount, sentAt, skipReason, status, updatedAt, invoice.id, invoice.gatewayInvoiceId, invoice.gatewayType, invoice.state, invoice.billingReason, invoice.transactionType, invoice.currency, invoice.total, invoice.userUuid, invoice.transactionUuid, invoice.paidAt, invoice.createdAt, invoice.updatedAt, original.id, original.eventType, original.status, original.retryCount, original.gatewayEventId, original.responseCode, original.sentAt, original.originalUuid, original.userUuid, original.transactionUuid, original.subscriptionUuid, original.invoiceUuid, original.createdAt, original.updatedAt, 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, transaction.id, transaction.amount, transaction.currency, transaction.status, transaction.description, transaction.createdAt, transaction.userUuid, transaction.checkoutSessionId, transaction.subscriptionUuid, transaction.gatewayTransactionId, transaction.gatewayPaymentIntentId, user.id, user.email, user.firstName, user.lastName, user.createdAt, user.updatedAt, webhook.id, webhook.clientId, webhook.url, webhook.failedSendAt, webhook.disabledAt, webhook.createdAt, webhook.updatedAt. |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: invoice, original, subscription, transaction, user, webhook. Unknown aliases return 400. |
createdAt | query | string (date-time) | No | Webhook delivery creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
eventType | query | string | No | Flo webhook 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: dispute.created, dispute.updated, dispute.won, dispute.lost, pre_dispute_alert.created, pre_dispute_alert.updated, subscription.created, subscription.updated, subscription.cancelled, subscription.renewed, subscription.reactivated, subscription.paused, subscription.resumed, subscription.expired, item.purchased, item.refunded, item.charged_back, invoice.created, invoice.deleted, invoice.updated, invoice.payment_failed, invoice.paid, invoice.overdue, payment.authorized, payment.capture_failed, payment.authorization_voided, payment.authorization_expired. |
disputeUuid | query | string | No | Flo dispute this event relates to. 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. |
gatewayEventId | query | string | No | Provider event 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. |
id | query | string | No | Webhook delivery id. 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. |
invoiceUuid | query | string | No | Flo invoice this event relates to. 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. |
originalUuid | query | string | No | Original webhook delivery id for resend attempts. 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. |
preDisputeAlertUuid | query | string | No | Flo Pre-Dispute Alert this event relates to. 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. |
responseCode | query | string | No | Last client response code. 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. |
retryCount | query | number | No | Delivery retry count. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
sentAt | query | string (date-time) | No | Webhook delivery sent timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
skipReason | query | string | No | Intentional webhook delivery exclusion reason. 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: endpoint_disabled, event_not_subscribed, endpoint_created_after_event, filter_context_missing, filter_not_matched. |
status | query | string | No | Webhook delivery 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, success, failed, retrying, skipped. |
subscriptionUuid | query | string | No | Flo subscription this event relates to. 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. |
transactionUuid | query | string | No | Flo transaction this event relates to. 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. |
updatedAt | query | string (date-time) | No | Webhook delivery 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 | Flo user this event relates to. 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[].createdAt | string (date-time) | Yes | |
data[].disputeUuid | string or null | No | Flo dispute this event relates to, when resolvable. |
data[].eventType | string | Yes | |
data[].gatewayEventId | string or null | No | |
data[].id | string | Yes | |
data[].invoice | object or null | No | Related invoice. Present only when requested with relation=invoice. |
data[].invoice.billingReason | string or null | No | Provider-reported billing reason. |
data[].invoice.createdAt | string (date-time) | Yes | When the invoice was created. |
data[].invoice.currency | string or null | No | |
data[].invoice.gateway | object or null | No | Owning gateway (non-secret fields). Present when the gateway relation is loaded. |
data[].invoice.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].invoice.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].invoice.gateway.environment | string | Yes | Allowed values: stage, production. |
data[].invoice.gateway.id | string | Yes | Gateway UUID. |
data[].invoice.gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].invoice.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].invoice.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].invoice.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[].invoice.gatewayType | string | Yes | The billing provider that produced this invoice. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].invoice.id | string | Yes | The Flopay invoice UUID. |
data[].invoice.paidAt | string (date-time) or null | No | When the invoice was paid by the provider. |
data[].invoice.state | string | Yes | The current invoice state. Allowed values: open, pending, processing, pastDue, paid, closed, failed, voided, unknown. |
data[].invoice.total | number or null | No | |
data[].invoice.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[].invoice.transaction.amount | number | Yes | |
data[].invoice.transaction.authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
data[].invoice.transaction.authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
data[].invoice.transaction.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].invoice.transaction.checkoutSessionId | string or null | No | Originating checkout session UUID. |
data[].invoice.transaction.createdAt | string (date-time) | Yes | Record creation timestamp. |
data[].invoice.transaction.currency | string | Yes | |
data[].invoice.transaction.description | string or null | Yes | |
data[].invoice.transaction.effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
data[].invoice.transaction.financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
data[].invoice.transaction.floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
data[].invoice.transaction.floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
data[].invoice.transaction.gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
data[].invoice.transaction.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].invoice.transaction.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].invoice.transaction.gateway.environment | string | Yes | Allowed values: stage, production. |
data[].invoice.transaction.gateway.id | string | Yes | Gateway UUID. |
data[].invoice.transaction.gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].invoice.transaction.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].invoice.transaction.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].invoice.transaction.gatewayChargeId | string or null | No | Original gateway charge identifier. |
data[].invoice.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[].invoice.transaction.gatewayTransactionId | string or null | No | Gateway transaction identifier. |
data[].invoice.transaction.id | string | Yes | |
data[].invoice.transaction.metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
data[].invoice.transaction.occurredAt | string (date-time) | Yes | |
data[].invoice.transaction.status | string | Yes | |
data[].invoice.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[].invoice.transaction.subscription.amount | number or null | Yes | The stored single-unit amount. |
data[].invoice.transaction.subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
data[].invoice.transaction.subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
data[].invoice.transaction.subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].invoice.transaction.subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
data[].invoice.transaction.subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
data[].invoice.transaction.subscription.createdAt | string (date-time) | Yes | When the row was created. |
data[].invoice.transaction.subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
data[].invoice.transaction.subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
data[].invoice.transaction.subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
data[].invoice.transaction.subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
data[].invoice.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[].invoice.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[].invoice.transaction.subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
data[].invoice.transaction.subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
data[].invoice.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[].invoice.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[].invoice.transaction.subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
data[].invoice.transaction.subscription.planDescription | string or null | Yes | The stored plan description when available. |
data[].invoice.transaction.subscription.planId | string | Yes | The stored plan identifier. |
data[].invoice.transaction.subscription.planName | string | Yes | The stored plan name. |
data[].invoice.transaction.subscription.quantity | number | Yes | The subscribed quantity. |
data[].invoice.transaction.subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
data[].invoice.transaction.subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
data[].invoice.transaction.subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
data[].invoice.transaction.subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
data[].invoice.transaction.subscription.total | number or null | Yes | The stored total amount. |
data[].invoice.transaction.subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
data[].invoice.transaction.subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
data[].invoice.transaction.subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].invoice.transaction.subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
data[].invoice.transaction.subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].invoice.transaction.subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
data[].invoice.transaction.subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
data[].invoice.transaction.subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
data[].invoice.transaction.type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
data[].invoice.transaction.userEmail | string or null | No | Customer email when the user relation is loaded. |
data[].invoice.transaction.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].invoice.transaction.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].invoice.transaction.userUuid | string or null | No | Linked Flopay user UUID. |
data[].invoice.transactionType | string or null | No | Provider-reported transaction type. |
data[].invoice.transactionUuid | string or null | No | Linked Flopay transaction UUID. |
data[].invoice.updatedAt | string (date-time) | Yes | When the invoice was last updated. |
data[].invoice.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].invoice.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].invoice.userUuid | string or null | No | Linked Flopay user UUID. |
data[].invoiceUuid | string or null | No | Flo invoice this event relates to, when resolvable. |
data[].original | object or null | No | Original delivery record. Present only when requested with relation=original. |
data[].originalUuid | string or null | No | |
data[].preDisputeAlertUuid | string or null | No | Flo Pre-Dispute Alert this event relates to, when Flo retains the alert. |
data[].requestBody | object | Yes | The Flo webhook payload that will be POSTed to the client. |
data[].responseBody | object or null | No | The last response body returned by the client endpoint. |
data[].responseCode | string or null | No | |
data[].retryCount | number | Yes | |
data[].sentAt | string (date-time) or null | No | |
data[].skipReason | string or null | No | Machine-readable reason an event was intentionally excluded before any delivery attempt. Allowed values: endpoint_disabled, event_not_subscribed, endpoint_created_after_event, filter_context_missing, filter_not_matched. |
data[].source | string or null | No | Allowed values: STRIPE, PAYPAL, WORLDPAY_CORPORATE_GATEWAY, CHARGEBACK. |
data[].status | string | Yes | Allowed values: pending, success, failed, retrying, skipped. |
data[].subscription | object or null | No | Related subscription. Present only when requested with relation=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 | Flo subscription this event relates to, when resolvable. |
data[].transaction | object or null | No | Related payment. Present only when requested with relation=transaction. |
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[].transactionUuid | string or null | No | Flo transaction this event relates to, when resolvable. |
data[].updatedAt | string (date-time) | Yes | |
data[].user | object or null | No | Related user. Present only when requested with relation=user. |
data[].user.clientUserId | string or null | No | |
data[].user.createdAt | string (date-time) | Yes | |
data[].user.email | string | Yes | |
data[].user.firstName | string | Yes | |
data[].user.id | string | Yes | |
data[].user.lastName | string | Yes | |
data[].user.updatedAt | string (date-time) | Yes | |
data[].userUuid | string or null | No | Flo user this event relates to, when resolvable. |
data[].webhook | object | No | Parent webhook endpoint. Present only when requested with relation=webhook. |
data[].webhook.clientId | string | Yes | |
data[].webhook.createdAt | string (date-time) | Yes | |
data[].webhook.disabledAt | string (date-time) or null | No | |
data[].webhook.events | array of string | Yes | |
data[].webhook.failedSendAt | string (date-time) or null | No | |
data[].webhook.id | string | Yes | |
data[].webhook.updatedAt | string (date-time) | Yes | |
data[].webhook.url | string | Yes | |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The supplied path or list query is 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. |