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 cc71a476426ea531d369de5441cde85ab81ab52c9764406e5f09501857d7ed32.
ClientWebhook_create
Create Webhook
Creates a webhook endpoint and signing secret. filter is optional: omission, null, {}, and empty selector arrays canonicalize to null (event-type-only delivery). Selector values use any-match within each set; when both sets are populated, one associated product must satisfy both its selected product id and at least one exact, case-sensitive tag. Events without product context do not match a configured filter.
| Policy | Value |
|---|---|
| Operation | POST /v1/webhooks |
| Class | mutating |
| Risk | high |
| Confirmation | required |
| Retry | same-idempotency-key |
| Rate-limit tier | restricted |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
events | body | array of string | Yes | The Flo webhook events that should be delivered to this endpoint. 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, item.reversed, invoice.created, invoice.deleted, invoice.updated, invoice.payment_failed, invoice.paid, invoice.overdue, payment.authorized, payment.capture_failed, payment.authorization_voided, payment.authorization_expired, customer.merged, payment_method.added, payment_method.removed, payment_method.default_changed. Minimum items: 1. |
filter | body | object or null | No | Optional product eligibility filter. Values within each selector use any-match; populated productIds and productTags combine with AND on the same associated product. Omit, null, {}, or empty arrays for event-type-only delivery. Events lacking product context do not match. PATCH omission preserves the current filter; null/empty clears it. |
filter.productIds | body | array of string (uuid) | No | Up to 50 active product UUIDs owned by the authenticated client. Maximum items: 50. |
filter.productTags | body | array of string | No | Up to 50 exact, case-sensitive tags present on active products owned by the client. Maximum items: 50. |
url | body | string (uri) | Yes | The client URL that should receive webhook deliveries. |
Result
Returns 201 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
clientId | string | Yes | Owning client UUID. |
createdAt | string (date-time) | Yes | |
disabledAt | string (date-time) or null | Yes | |
events | array of string | Yes | |
failedSendAt | string (date-time) or null | Yes | |
filter | object or null | Yes | Optional product filter. At least one associated product must match every populated selector set. Null delivers every subscribed event. |
filter.productIds | array of string (uuid) | No | Up to 50 active product UUIDs owned by the authenticated client. Maximum items: 50. |
filter.productTags | array of string | No | Up to 50 exact, case-sensitive tags present on active products owned by the client. Maximum items: 50. |
id | string | Yes | |
signingSecret | string | Yes | Secret used to sign outbound webhook deliveries with the Flo-Signature header. |
updatedAt | string (date-time) | Yes | |
url | string | Yes |
Errors
| Status | Description |
|---|---|
400 | The URL, event subscriptions, or filter shape is malformed; selectors are duplicated or exceed their limits; or a selected product id/tag is unavailable in the authenticated client’s active catalog. Unknown, inactive, deleted, stale, and foreign selectors share the same tenant-safe unavailable-selector response. |
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. |
ClientWebhook_delete
Delete Webhook
Deletes a client webhook endpoint and its delivery log entries.
| Policy | Value |
|---|---|
| Operation | DELETE /v1/webhooks/{id} |
| Class | mutating |
| Risk | critical |
| Confirmation | required |
| Retry | same-idempotency-key |
| Rate-limit tier | restricted |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Result
Returns 204 with no body.
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. |
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. |
ClientWebhook_update
Update Webhook
Updates the webhook URL, subscriptions, and/or product filter. Omitting filter preserves it; null, {}, or empty selector arrays clear it; a non-empty object replaces both selector sets. Any update also clears failed/disabled markers so the endpoint can receive new eligible deliveries.
| Policy | Value |
|---|---|
| Operation | PATCH /v1/webhooks/{id} |
| Class | mutating |
| Risk | high |
| Confirmation | required |
| Retry | same-idempotency-key |
| Rate-limit tier | restricted |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | |
events | body | array of string | No | The Flo webhook events that should be delivered to this endpoint. 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, item.reversed, invoice.created, invoice.deleted, invoice.updated, invoice.payment_failed, invoice.paid, invoice.overdue, payment.authorized, payment.capture_failed, payment.authorization_voided, payment.authorization_expired, customer.merged, payment_method.added, payment_method.removed, payment_method.default_changed. Minimum items: 1. |
filter | body | object or null | No | Optional product eligibility filter. Values within each selector use any-match; populated productIds and productTags combine with AND on the same associated product. Omit, null, {}, or empty arrays for event-type-only delivery. Events lacking product context do not match. PATCH omission preserves the current filter; null/empty clears it. |
filter.productIds | body | array of string (uuid) | No | Up to 50 active product UUIDs owned by the authenticated client. Maximum items: 50. |
filter.productTags | body | array of string | No | Up to 50 exact, case-sensitive tags present on active products owned by the client. Maximum items: 50. |
url | body | string (uri) | No | The client URL that should receive webhook deliveries. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
clientId | string | Yes | Owning client UUID. |
createdAt | string (date-time) | Yes | |
disabledAt | string (date-time) or null | Yes | |
events | array of string | Yes | |
failedSendAt | string (date-time) or null | Yes | |
filter | object or null | Yes | Optional product filter. At least one associated product must match every populated selector set. Null delivers every subscribed event. |
filter.productIds | array of string (uuid) | No | Up to 50 active product UUIDs owned by the authenticated client. Maximum items: 50. |
filter.productTags | array of string | No | Up to 50 exact, case-sensitive tags present on active products owned by the client. Maximum items: 50. |
id | string | Yes | |
signingSecret | string | Yes | Secret used to sign outbound webhook deliveries with the Flo-Signature header. |
updatedAt | string (date-time) | Yes | |
url | string | Yes |
Errors
| Status | Description |
|---|---|
400 | The request or filter shape is malformed; selectors are duplicated or exceed their limits; or a selected product id/tag is unavailable in the authenticated client’s active catalog. Unknown, inactive, deleted, stale, and foreign selectors share the same tenant-safe unavailable-selector response. |
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, item.reversed, invoice.created, invoice.deleted, invoice.updated, invoice.payment_failed, invoice.paid, invoice.overdue, payment.authorized, payment.capture_failed, payment.authorization_voided, payment.authorization_expired, customer.merged, payment_method.added, payment_method.removed, payment_method.default_changed. |
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.buyerBusinessDetails | object or null | No | The buyer's business details at this merchant as they stood when Flo created the invoice: customerType (business or individual), legalName, address (street1, street2, city, region, postalCode, ISO 3166-1 alpha-2 country) and taxId (type, normalised value). A later change to the buyer's details reaches only the next invoice. null when the buyer had none, and for invoices issued by a payment provider. |
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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
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.hostedInvoiceUrl | string or null | No | The invoice's hosted page: no sign-in, behind an unguessable token. For invoices FloPay issues itself it shows both parties' identity, each line, the total and the tax note. Provider invoices carry the provider's page. null when the invoice has none. |
invoice.id | string | Yes | The Flopay invoice UUID. |
invoice.invoiceNumber | string or null | No | The invoice number. FloPay numbers the invoices it issues itself per merchant as <prefix><sequence> (the merchant's prefix, default INV-, and a sequence zero-padded to 6 digits, e.g. INV-000001); a number is never reused or changed. Provider invoices keep the provider's number. null when the invoice has none. |
invoice.invoicePdfUrl | string or null | No | The invoice's PDF, a sibling of hostedInvoiceUrl with the same content and the same access rule. null when the invoice has none. |
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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
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.gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
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.refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
invoice.transaction.refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
invoice.transaction.refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
invoice.transaction.refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
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.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
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.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
invoice.transaction.subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
invoice.transaction.subscription.meteredItems[].name | string | Yes | |
invoice.transaction.subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
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.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
invoice.transaction.subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
invoice.transaction.subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
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, FLO. |
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.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
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.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
subscription.meteredItems[].name | string | Yes | |
subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
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.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
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.gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
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.refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
transaction.refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
transaction.refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
transaction.refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
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.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
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.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
transaction.subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
transaction.subscription.meteredItems[].name | string | Yes | |
transaction.subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
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.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
transaction.subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
transaction.subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
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, item.reversed, invoice.created, invoice.deleted, invoice.updated, invoice.payment_failed, invoice.paid, invoice.overdue, payment.authorized, payment.capture_failed, payment.authorization_voided, payment.authorization_expired, customer.merged, payment_method.added, payment_method.removed, payment_method.default_changed. |
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.buyerBusinessDetails | object or null | No | The buyer's business details at this merchant as they stood when Flo created the invoice: customerType (business or individual), legalName, address (street1, street2, city, region, postalCode, ISO 3166-1 alpha-2 country) and taxId (type, normalised value). A later change to the buyer's details reaches only the next invoice. null when the buyer had none, and for invoices issued by a payment provider. |
data[].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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
data[].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.hostedInvoiceUrl | string or null | No | The invoice's hosted page: no sign-in, behind an unguessable token. For invoices FloPay issues itself it shows both parties' identity, each line, the total and the tax note. Provider invoices carry the provider's page. null when the invoice has none. |
data[].invoice.id | string | Yes | The Flopay invoice UUID. |
data[].invoice.invoiceNumber | string or null | No | The invoice number. FloPay numbers the invoices it issues itself per merchant as <prefix><sequence> (the merchant's prefix, default INV-, and a sequence zero-padded to 6 digits, e.g. INV-000001); a number is never reused or changed. Provider invoices keep the provider's number. null when the invoice has none. |
data[].invoice.invoicePdfUrl | string or null | No | The invoice's PDF, a sibling of hostedInvoiceUrl with the same content and the same access rule. null when the invoice has none. |
data[].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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
data[].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.gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
data[].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.refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
data[].invoice.transaction.refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
data[].invoice.transaction.refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
data[].invoice.transaction.refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
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.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
data[].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.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
data[].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.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
data[].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, FLO. |
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.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
data[].subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
data[].subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
data[].subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
data[].subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
data[].subscription.createdAt | string (date-time) | Yes | When the row was created. |
data[].subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
data[].subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
data[].subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
data[].subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
data[].subscription.gateway.id | string | Yes | Gateway UUID. |
data[].subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].subscription.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
data[].subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
data[].subscription.gatewaySubscriptionId | string | Yes | The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized flo_<uuid> identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway. |
data[].subscription.gatewayType | string | Yes | The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read ownership to tell the two apart. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
data[].subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
data[].subscription.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
data[].subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
data[].subscription.meteredItems[].name | string | Yes | |
data[].subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
data[].subscription.ownership | string | Yes | Who owns the billing schedule. provider means the gateway holds the subscription object and drives renewals; flo means Flopay holds the schedule and drives renewals itself, charging through the gateway named by gatewayType. Allowed values: flo, provider. |
data[].subscription.pauseState | string or null | Yes | Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: scheduled, active. |
data[].subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
data[].subscription.planDescription | string or null | Yes | The stored plan description when available. |
data[].subscription.planId | string | Yes | The stored plan identifier. |
data[].subscription.planName | string | Yes | The stored plan name. |
data[].subscription.quantity | number | Yes | The subscribed quantity. |
data[].subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
data[].subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
data[].subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
data[].subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
data[].subscription.total | number or null | Yes | The stored total amount. |
data[].subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
data[].subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
data[].subscription.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
data[].subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
data[].subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
data[].subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
data[].subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
data[].subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
data[].subscriptionUuid | string or null | No | 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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
data[].transaction.gatewayChargeId | string or null | No | Original gateway charge identifier. |
data[].transaction.gatewayPaymentIntentId | string or null | No | Opaque provider payment-object identifier, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility. |
data[].transaction.gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
data[].transaction.gatewayTransactionId | string or null | No | Gateway transaction identifier. |
data[].transaction.id | string | Yes | |
data[].transaction.metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
data[].transaction.occurredAt | string (date-time) | Yes | |
data[].transaction.refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
data[].transaction.refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
data[].transaction.refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
data[].transaction.refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
data[].transaction.status | string | Yes | |
data[].transaction.subscription | object | No | Linked subscription (non-secret fields incl. metadata). Present only when the subscription relation is loaded and the payment is tied to a subscription. |
data[].transaction.subscription.amount | number or null | Yes | The stored single-unit amount. |
data[].transaction.subscription.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
data[].transaction.subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
data[].transaction.subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
data[].transaction.subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].transaction.subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
data[].transaction.subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
data[].transaction.subscription.createdAt | string (date-time) | Yes | When the row was created. |
data[].transaction.subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
data[].transaction.subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
data[].transaction.subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
data[].transaction.subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].transaction.subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].transaction.subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
data[].transaction.subscription.gateway.id | string | Yes | Gateway UUID. |
data[].transaction.subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].transaction.subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].transaction.subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].transaction.subscription.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
data[].transaction.subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
data[].transaction.subscription.gatewaySubscriptionId | string | Yes | The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized flo_<uuid> identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway. |
data[].transaction.subscription.gatewayType | string | Yes | The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read ownership to tell the two apart. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].transaction.subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
data[].transaction.subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
data[].transaction.subscription.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
data[].transaction.subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
data[].transaction.subscription.meteredItems[].name | string | Yes | |
data[].transaction.subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
data[].transaction.subscription.ownership | string | Yes | Who owns the billing schedule. provider means the gateway holds the subscription object and drives renewals; flo means Flopay holds the schedule and drives renewals itself, charging through the gateway named by gatewayType. Allowed values: flo, provider. |
data[].transaction.subscription.pauseState | string or null | Yes | Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: scheduled, active. |
data[].transaction.subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
data[].transaction.subscription.planDescription | string or null | Yes | The stored plan description when available. |
data[].transaction.subscription.planId | string | Yes | The stored plan identifier. |
data[].transaction.subscription.planName | string | Yes | The stored plan name. |
data[].transaction.subscription.quantity | number | Yes | The subscribed quantity. |
data[].transaction.subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
data[].transaction.subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
data[].transaction.subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
data[].transaction.subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
data[].transaction.subscription.total | number or null | Yes | The stored total amount. |
data[].transaction.subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
data[].transaction.subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
data[].transaction.subscription.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
data[].transaction.subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
data[].transaction.subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
data[].transaction.subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].transaction.subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
data[].transaction.subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].transaction.subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
data[].transaction.subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
data[].transaction.subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
data[].transaction.type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
data[].transaction.userEmail | string or null | No | Customer email when the user relation is loaded. |
data[].transaction.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].transaction.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].transaction.userUuid | string or null | No | Linked Flopay user UUID. |
data[].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. |
ClientWebhookEvent_resend
Resend Webhook Event
Resets the selected delivery in place under its stable event id and republishes it. The delivery must belong to the authenticated client, its endpoint must be enabled, and its persisted initial filter decision must not be excluded.
| Policy | Value |
|---|---|
| Operation | PUT /v1/webhooks/events/{id}/resend |
| Class | mutating |
| Risk | high |
| Confirmation | required |
| Retry | manual-reconciliation |
| Rate-limit tier | restricted |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Result
Returns 202 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.buyerBusinessDetails | object or null | No | The buyer's business details at this merchant as they stood when Flo created the invoice: customerType (business or individual), legalName, address (street1, street2, city, region, postalCode, ISO 3166-1 alpha-2 country) and taxId (type, normalised value). A later change to the buyer's details reaches only the next invoice. null when the buyer had none, and for invoices issued by a payment provider. |
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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
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.hostedInvoiceUrl | string or null | No | The invoice's hosted page: no sign-in, behind an unguessable token. For invoices FloPay issues itself it shows both parties' identity, each line, the total and the tax note. Provider invoices carry the provider's page. null when the invoice has none. |
invoice.id | string | Yes | The Flopay invoice UUID. |
invoice.invoiceNumber | string or null | No | The invoice number. FloPay numbers the invoices it issues itself per merchant as <prefix><sequence> (the merchant's prefix, default INV-, and a sequence zero-padded to 6 digits, e.g. INV-000001); a number is never reused or changed. Provider invoices keep the provider's number. null when the invoice has none. |
invoice.invoicePdfUrl | string or null | No | The invoice's PDF, a sibling of hostedInvoiceUrl with the same content and the same access rule. null when the invoice has none. |
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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
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.gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
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.refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
invoice.transaction.refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
invoice.transaction.refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
invoice.transaction.refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
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.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
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.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
invoice.transaction.subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
invoice.transaction.subscription.meteredItems[].name | string | Yes | |
invoice.transaction.subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
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.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
invoice.transaction.subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
invoice.transaction.subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
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, FLO. |
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.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
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.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
subscription.meteredItems[].name | string | Yes | |
subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
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.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
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.gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
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.refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
transaction.refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
transaction.refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
transaction.refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
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.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
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.gateway.sessionMode | string | Yes | Whether this gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both. Allowed values: both, on_session, off_session. |
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.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
transaction.subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
transaction.subscription.meteredItems[].name | string | Yes | |
transaction.subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
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.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
transaction.subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
transaction.subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
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. |
409 | The endpoint is disabled, source provenance is unavailable, or the delivery was excluded by its persisted initial product-filter decision. |
ClientWebhookEvent_resendMany
Resend Webhook Events
Resends every webhook delivery owned by the authenticated client that matches the supplied list query. Eligible deliveries are reset in place to pending under their stable event ids and republished. Disabled endpoints and deliveries excluded by their persisted initial filter decision are returned in skippedIds; they are not queued. Supports the same whitelisted filters as the list endpoint.
| Policy | Value |
|---|---|
| Operation | POST /v1/webhooks/events/resend |
| Class | mutating |
| Risk | high |
| Confirmation | required |
| Retry | manual-reconciliation |
| Rate-limit tier | restricted |
| Roles | owner, admin |
| Scopes | mcp:write |
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, item.reversed, invoice.created, invoice.deleted, invoice.updated, invoice.payment_failed, invoice.paid, invoice.overdue, payment.authorized, payment.capture_failed, payment.authorization_voided, payment.authorization_expired, customer.merged, payment_method.added, payment_method.removed, payment_method.default_changed. |
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 202 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
failedCount | number | Yes | Number of matched webhook events that were reset to pending but whose re-queue onto the outbox broker failed. They remain pending and can be resent again. |
failedIds | array of string | Yes | Ids of the matched webhook events that were reset to pending but could not be re-queued onto the outbox broker. Resend them again to complete redelivery. |
resentCount | number | Yes | Number of matched webhook events that were reset to pending and re-queued for delivery. |
resentIds | array of string | Yes | Ids of the matched webhook events that were re-queued for delivery. |
skippedCount | number | Yes | Number of matched webhook events that were skipped because their webhook endpoint is disabled. |
skippedIds | array of string | Yes | Ids of the matched webhook events that were skipped because their webhook endpoint is disabled. |
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. |