FloPayFloPay
Webhooks

Payloads

Field-level schema for Flo webhook payloads.

Payloads

Each Flo webhook message contains one normalized Flo event payload.

For concrete examples of delivered events, see Events.

Common Fields

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a00",
  "eventVersion": "v1",
  "objectType": "subscription",
  "eventType": "subscription.created",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "subscription": {
    "uuid": "d8a2ad28-b98f-4cb6-bf46-f11cc0f5df16",
    "id": "plan_pro",
    "name": "Pro",
    "description": "Pro subscription",
    "startDate": "2026-04-10T00:00:00.000Z",
    "endDate": "2026-05-10T00:00:00.000Z",
    "state": "active",
    "quantity": 1,
    "currency": "USD",
    "amount": 29,
    "total": 29,
    "cancelAt": null,
    "canceledAt": null,
    "trialEnd": null,
    "pausedAt": null,
    "resumeAt": null,
    "metadata": null,
    "invoiceDetails": null
  }
}

Event Envelope

  • eventId: The Flo webhook delivery identifier for this endpoint delivery. It is not the upstream gateway event id, and automatic retries for the same delivery reuse the same eventId.
  • eventVersion: The webhook schema version.
  • objectType: The top-level Flo resource family for the event.
  • eventType: The normalized Flo event type.
  • user: The canonical user object for the event.
  • subscription: Present on subscription events. May also be present on invoice events as related enrichment.
  • item: Present on item events. May also be present on invoice events as related enrichment.
  • invoice: Present on invoice events.
  • payment: Present on payment authorisation lifecycle events.

Compatibility Fields

New integrations should build against user, eventType, objectType, and the explicit resource root (subscription, item, invoice, or payment). On invoice events, root-level subscription and item are enrichment fields. Flo includes them when the invoice points at a linked local transaction that resolves to a checkout subscription and/or checkout item.

User Object

{
  "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
  "clientUserId": "user_123",
  "email": "user@example.com"
}

Payment Payload

Payment authorisation events include the provider-neutral payment state. id is FloPay's payment UUID for the trusted-server capture and cancellation operations; it is not a provider intent id.

{
  "id": "3c54b6ac-7ad5-4e56-9c2c-5a80c2ef40d0",
  "checkoutSessionId": "fd4475e4-dc19-4439-b830-c9c8f67a35e7",
  "amount": 49.99,
  "currency": "GBP",
  "status": "authorized",
  "authorizationExpiresAt": "2026-08-11T14:30:00.000Z",
  "authorizationVoidReason": null
}
  • checkoutSessionId: FloPay checkout session associated with the payment.
  • amount / currency: Full authorised amount in the payment currency.
  • status: Canonical payment state. Authorisation events use authorized or voided; see the payment state reference.
  • authorizationExpiresAt: Provider-derived capture deadline for an active hold.
  • authorizationVoidReason: merchant_requested, expired, or provider_canceled after a hold becomes voided; otherwise null.

Subscription Payload

  • uuid: Flo's checkout subscription UUID when the event is linked to a checkout session.
  • id: The checkout subscription's provider plan id.
  • name / description: The checkout subscription's provider-backed display fields.
{
  "uuid": "d8a2ad28-b98f-4cb6-bf46-f11cc0f5df16",
  "id": "plan_pro",
  "name": "Pro",
  "description": "Pro subscription",
  "startDate": "2026-04-10T00:00:00.000Z",
  "endDate": "2026-05-10T00:00:00.000Z",
  "state": "active",
  "quantity": 1,
  "currency": "USD",
  "amount": 29,
  "total": 29,
  "cancelAt": null,
  "canceledAt": null,
  "trialEnd": null,
  "pausedAt": null,
  "resumeAt": null,
  "metadata": null,
  "invoiceDetails": null
}

Item Payload

  • uuid: Flo's checkout item UUID when the event is linked to a checkout session.
  • id: The checkout item's provider item id.
  • name / description: The checkout item's provider-backed display fields.
  • amount / currency: The value and currency of the item event. On item.charged_back, the amount is money withdrawn by the provider dispute.
{
  "uuid": "da634f98-8748-4e90-bb5d-f3df74003b57",
  "id": "item_123",
  "name": "Product",
  "description": "Product description",
  "quantity": 1,
  "currency": "USD",
  "amount": 29,
  "total": 29,
  "invoiceState": "paid",
  "metadata": null,
  "invoiceDetails": null
}

For item money-movement events, use eventType as the primary branch and invoiceDetails.transactionType as the financial discriminator:

EventinvoiceDetails.transactionTypeMeaning
item.refundedrefundA genuine merchant or administrative refund.
item.charged_backchargebackMoney was withdrawn because of a provider dispute.

The chargeback case keeps the existing item and invoiceDetails field shapes. For example:

{
  "eventType": "item.charged_back",
  "item": {
    "amount": 29,
    "currency": "USD",
    "invoiceState": "voided",
    "invoiceDetails": {
      "transactionType": "chargeback",
      "transactionId": "dp_123",
      "chargeId": "ch_123",
      "currency": "USD"
    }
  }
}

A genuine refund carries invoiceDetails.transactionType: "refund". Do not infer a chargeback from item.refunded or from provider-specific trace fields.

Invoice Payload

{
  "id": "7bb5ce14-59e0-41ee-8fb7-84d6967cdb68",
  "invoiceNumber": "FLO-1001",
  "state": "pastDue",
  "billingReason": "subscription_cycle",
  "currency": "GBP",
  "amountDue": 27,
  "amountPaid": 0,
  "subtotal": 27,
  "total": 27,
  "paidAt": null,
  "hostedInvoiceUrl": "https://example.com/invoice",
  "invoicePdfUrl": "https://example.com/invoice.pdf",
  "invoiceDetails": null
}

Invoice Event Enrichment

  • On invoice events, Flo may include root-level subscription and/or item alongside invoice.
  • These related objects are resolved from the linked local transaction.
  • An invoice event can include either, both, or neither of these related objects.
{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a00",
  "eventVersion": "v1",
  "objectType": "invoice",
  "eventType": "invoice.paid",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "invoice": {
    "id": "7bb5ce14-59e0-41ee-8fb7-84d6967cdb68",
    "invoiceNumber": "FLO-1001",
    "state": "paid",
    "billingReason": "subscription_cycle",
    "currency": "GBP",
    "amountDue": 27,
    "amountPaid": 27,
    "subtotal": 27,
    "total": 27,
    "paidAt": "2026-04-11T10:20:00.000Z",
    "hostedInvoiceUrl": "https://example.com/invoice",
    "invoicePdfUrl": "https://example.com/invoice.pdf",
    "invoiceDetails": {
      "gatewayEventType": "invoice.paid",
      "invoiceId": "in_123",
      "invoiceStatus": "paid",
      "billingReason": "subscription_cycle",
      "transactionId": "pi_123",
      "currency": "GBP",
      "amountDue": 27,
      "amountPaid": 27,
      "total": 27
    }
  },
  "subscription": {
    "uuid": "d8a2ad28-b98f-4cb6-bf46-f11cc0f5df16",
    "id": "hub-membership",
    "name": "Hub Membership",
    "description": "Hub membership billed every four weeks",
    "quantity": 1,
    "currency": "GBP",
    "amount": 22,
    "total": 22,
    "metadata": {
      "source": "checkout-subscription"
    }
  },
  "item": {
    "uuid": "da634f98-8748-4e90-bb5d-f3df74003b57",
    "id": "priority-support",
    "name": "Priority Support",
    "description": "Priority support add-on",
    "quantity": 1,
    "currency": "GBP",
    "amount": 5,
    "total": 5,
    "metadata": {
      "source": "checkout-item"
    }
  }
}
{
  "uuid": "d8a2ad28-b98f-4cb6-bf46-f11cc0f5df16",
  "id": "hub-membership",
  "name": "Hub Membership",
  "description": "Hub membership billed every four weeks",
  "quantity": 1,
  "currency": "GBP",
  "amount": 22,
  "total": 22,
  "metadata": {
    "source": "checkout-subscription"
  }
}
{
  "uuid": "da634f98-8748-4e90-bb5d-f3df74003b57",
  "id": "priority-support",
  "name": "Priority Support",
  "description": "Priority support add-on",
  "quantity": 1,
  "currency": "GBP",
  "amount": 5,
  "total": 5,
  "metadata": {
    "source": "checkout-item"
  }
}

Invoice Details

invoiceDetails is optional on subscription, item, and invoice events. When present, it includes invoice and payment context associated with the Flo event.

Most integrations should build against eventType, objectType, and the explicit resource root (subscription, item, or invoice). invoiceDetails.gatewayEventType is additional trace context and should not be the primary switch for business logic.

{
  "gatewayEventType": "invoice.paid",
  "invoiceId": "in_123",
  "invoiceNumber": "FLO-1001",
  "invoiceStatus": "paid",
  "billingReason": "subscription_cycle",
  "invoicePaymentId": "inpay_123",
  "transactionId": "pi_123",
  "transactionType": "payment_intent",
  "paymentIntentId": "pi_123",
  "chargeId": "ch_123",
  "paymentRecordId": null,
  "receiptNumber": null,
  "hostedInvoiceUrl": "https://...",
  "invoicePdfUrl": "https://...",
  "paidAt": "2026-04-10T12:00:00.000Z",
  "currency": "USD",
  "amountDue": 29,
  "amountPaid": 29,
  "subtotal": 29,
  "total": 29
}

Events

Flo webhook event types and example payloads.

Delivery

Delivery expectations for Flo webhooks.

On this page

PayloadsCommon FieldsEvent EnvelopeCompatibility FieldsUser ObjectPayment PayloadSubscription PayloadItem PayloadInvoice PayloadInvoice Event EnrichmentInvoice-related Subscription PayloadInvoice-related Item PayloadInvoice Details