Events

Flo currently emits four normalized resource families: subscription, item, invoice, and payment.

Examples below are illustrative. Optional fields may be null or omitted depending on the billing activity that produced the event. The top-level eventId shown in each example is Flo's delivery identifier for that webhook delivery, not the upstream gateway event id. On invoice events, Flo may also include root-level subscription and/or item when it can resolve linked checkout records from the local transaction.

The outbound event shape is the same regardless of which gateway produced the underlying activity. For the inbound PayPal event catalog and its mapping to the outbound events on this page, see PayPal webhook events.

Event Catalog

Event Type	Payload Root	Meaning
`subscription.created`	`subscription`	A new subscription has been created in Flo.
`subscription.updated`	`subscription`	A subscription changed without being cancelled, renewed, paused, resumed, or reactivated.
`subscription.cancelled`	`subscription`	A subscription has been scheduled for cancellation or cancelled in Flo.
`subscription.renewed`	`subscription`	A recurring subscription period was successfully billed.
`subscription.reactivated`	`subscription`	A previously cancelled subscription was restored.
`subscription.paused`	`subscription`	A subscription has been paused.
`subscription.resumed`	`subscription`	A paused subscription has resumed.
`subscription.expired`	`subscription`	A subscription has ended and is no longer active.
`item.purchased`	`item`	A one-off item or invoice line was successfully purchased.
`item.refunded`	`item`	A previously purchased item was refunded.
`item.charged_back`	`item`	Money was withdrawn after a provider dispute.
`invoice.created`	`invoice`	A new Flo invoice has been created.
`invoice.updated`	`invoice`	A Flo invoice changed without being deleted, paid, or becoming overdue.
`invoice.deleted`	`invoice`	A Flo invoice was deleted.
`invoice.paid`	`invoice`	A Flo invoice was paid successfully.
`invoice.overdue`	`invoice`	A Flo invoice is overdue.
`payment.authorized`	`payment`	A card hold is active and awaiting capture. Funds are not paid.
`payment.capture_failed`	`payment`	A later capture attempt failed without producing a paid outcome.
`payment.authorization_voided`	`payment`	A merchant released an uncaptured hold.
`payment.authorization_expired`	`payment`	The provider expired an uncaptured hold.

Payment authorisation events

The payment events report the hold lifecycle. None is a successful-purchase signal. For an item-only manual-capture checkout, item.purchased remains the canonical fulfilment event and is emitted only after the full capture succeeds. There is no payment.captured event.

All four events use this provider-neutral payload shape:

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41b01",
  "eventVersion": "v1",
  "objectType": "payment",
  "eventType": "payment.authorized",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "customer_123",
    "email": "customer@example.com"
  },
  "payment": {
    "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
  }
}

Interpret the event-specific fields as follows:

Event	Expected state
`payment.authorized`	`payment.status` is `authorized`; retain `payment.id` and act before `authorizationExpiresAt`.
`payment.capture_failed`	No paid state was produced. Re-read the payment before retrying the same logical capture.
`payment.authorization_voided`	`payment.status` is `voided` and `authorizationVoidReason` is `merchant_requested`.
`payment.authorization_expired`	`payment.status` is `voided` and `authorizationVoidReason` is `expired`.

Subscription Events

`subscription.created`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a01",
  "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": "hub-membership",
    "name": "Hub Membership",
    "description": "Hub membership billed every four weeks",
    "state": "active",
    "quantity": 1,
    "currency": "GBP",
    "amount": 22,
    "total": 22,
    "startDate": "2026-04-11T00:00:00.000Z",
    "endDate": "2026-05-09T00:00:00.000Z"
  }
}

`subscription.updated`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a02",
  "eventVersion": "v1",
  "objectType": "subscription",
  "eventType": "subscription.updated",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "subscription": {
    "uuid": "d8a2ad28-b98f-4cb6-bf46-f11cc0f5df16",
    "id": "hub-membership-plus",
    "name": "Hub Membership Plus",
    "description": "Hub membership plus billed every four weeks",
    "state": "active",
    "quantity": 2,
    "currency": "GBP",
    "amount": 22,
    "total": 44,
    "startDate": "2026-04-11T00:00:00.000Z",
    "endDate": "2026-05-09T00:00:00.000Z"
  }
}

`subscription.cancelled`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a03",
  "eventVersion": "v1",
  "objectType": "subscription",
  "eventType": "subscription.cancelled",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "subscription": {
    "uuid": "d8a2ad28-b98f-4cb6-bf46-f11cc0f5df16",
    "id": "hub-membership",
    "name": "Hub Membership",
    "description": "Hub membership billed every four weeks",
    "state": "canceled",
    "quantity": 1,
    "currency": "GBP",
    "amount": 22,
    "total": 22,
    "cancelAt": "2026-05-09T00:00:00.000Z",
    "canceledAt": "2026-04-11T10:15:00.000Z"
  }
}

`subscription.renewed`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a04",
  "eventVersion": "v1",
  "objectType": "subscription",
  "eventType": "subscription.renewed",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "subscription": {
    "uuid": "d8a2ad28-b98f-4cb6-bf46-f11cc0f5df16",
    "id": "hub-membership",
    "name": "Hub Membership",
    "description": "Hub membership billed every four weeks",
    "state": "active",
    "quantity": 1,
    "currency": "GBP",
    "amount": 22,
    "total": 22,
    "startDate": "2026-04-11T00:00:00.000Z",
    "endDate": "2026-05-09T00:00:00.000Z",
    "invoiceDetails": {
      "gatewayEventType": "invoice.paid",
      "invoiceId": "in_123",
      "invoiceStatus": "paid",
      "transactionId": "txn_123",
      "paidAt": "2026-04-11T10:20:00.000Z",
      "currency": "GBP",
      "amountPaid": 22,
      "total": 22
    }
  }
}

`subscription.reactivated`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a05",
  "eventVersion": "v1",
  "objectType": "subscription",
  "eventType": "subscription.reactivated",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "subscription": {
    "uuid": "d8a2ad28-b98f-4cb6-bf46-f11cc0f5df16",
    "id": "hub-membership",
    "name": "Hub Membership",
    "description": "Hub membership billed every four weeks",
    "state": "active",
    "quantity": 1,
    "currency": "GBP",
    "amount": 22,
    "total": 22,
    "cancelAt": null,
    "canceledAt": null
  }
}

`subscription.paused`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a06",
  "eventVersion": "v1",
  "objectType": "subscription",
  "eventType": "subscription.paused",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "subscription": {
    "uuid": "d8a2ad28-b98f-4cb6-bf46-f11cc0f5df16",
    "id": "hub-membership",
    "name": "Hub Membership",
    "description": "Hub membership billed every four weeks",
    "state": "paused",
    "quantity": 1,
    "currency": "GBP",
    "amount": 22,
    "total": 22,
    "pausedAt": "2026-04-11T10:30:00.000Z",
    "resumeAt": "2026-05-11T10:30:00.000Z"
  }
}

`subscription.resumed`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a07",
  "eventVersion": "v1",
  "objectType": "subscription",
  "eventType": "subscription.resumed",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "subscription": {
    "uuid": "d8a2ad28-b98f-4cb6-bf46-f11cc0f5df16",
    "id": "hub-membership",
    "name": "Hub Membership",
    "description": "Hub membership billed every four weeks",
    "state": "active",
    "quantity": 1,
    "currency": "GBP",
    "amount": 22,
    "total": 22,
    "pausedAt": null,
    "resumeAt": null
  }
}

`subscription.expired`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a08",
  "eventVersion": "v1",
  "objectType": "subscription",
  "eventType": "subscription.expired",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "subscription": {
    "uuid": "d8a2ad28-b98f-4cb6-bf46-f11cc0f5df16",
    "id": "hub-membership",
    "name": "Hub Membership",
    "description": "Hub membership billed every four weeks",
    "state": "expired",
    "quantity": 1,
    "currency": "GBP",
    "amount": 22,
    "total": 22,
    "endDate": "2026-05-09T00:00:00.000Z"
  }
}

These events are produced from subscription lifecycle changes and recurring billing activity.

Item Events

Required migration for backend v1.7.1. Before enabling the release, add item.charged_back to every applicable webhook endpoint subscription and treat its amount as money withdrawn. Move any branch that detects a PayPal chargeback from item.refunded to this new event. Existing payload field shapes are unchanged.

`item.purchased`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a09",
  "eventVersion": "v1",
  "objectType": "item",
  "eventType": "item.purchased",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "item": {
    "uuid": "da634f98-8748-4e90-bb5d-f3df74003b57",
    "id": "priority-support",
    "name": "Priority Support",
    "description": "Priority Support",
    "quantity": 1,
    "currency": "GBP",
    "amount": 5,
    "total": 5,
    "invoiceState": "paid",
    "invoiceDetails": {
      "gatewayEventType": "invoice.paid",
      "invoiceId": "in_123",
      "invoiceStatus": "paid",
      "transactionId": "txn_123",
      "paidAt": "2026-04-11T10:20:00.000Z",
      "currency": "GBP",
      "amountPaid": 27,
      "total": 27
    }
  }
}

`item.refunded`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a0a",
  "eventVersion": "v1",
  "objectType": "item",
  "eventType": "item.refunded",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "item": {
    "uuid": "da634f98-8748-4e90-bb5d-f3df74003b57",
    "id": "priority-support",
    "name": "Priority Support",
    "description": "Priority Support",
    "quantity": 1,
    "currency": "GBP",
    "amount": 5,
    "total": 5,
    "invoiceState": "voided",
    "invoiceDetails": {
      "gatewayEventType": "refund.created",
      "invoiceId": "in_123",
      "invoiceStatus": "paid",
      "transactionId": "re_123",
      "transactionType": "refund",
      "chargeId": "ch_123",
      "currency": "GBP",
      "amountPaid": 0,
      "total": 5
    }
  }
}

item.refunded is reserved for genuine merchant or administrative refunds. Chargebacks do not emit item.refunded.

`item.charged_back`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a10",
  "eventVersion": "v1",
  "objectType": "item",
  "eventType": "item.charged_back",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "item": {
    "uuid": "da634f98-8748-4e90-bb5d-f3df74003b57",
    "id": "priority-support",
    "name": "Priority Support",
    "description": "Priority Support",
    "quantity": 1,
    "currency": "GBP",
    "amount": 5,
    "total": 5,
    "invoiceState": "voided",
    "invoiceDetails": {
      "gatewayEventType": "charge.dispute.funds_withdrawn",
      "invoiceId": "in_123",
      "invoiceStatus": "under_review",
      "transactionId": "dp_123",
      "transactionType": "chargeback",
      "chargeId": "ch_123",
      "currency": "GBP",
      "amountPaid": 0,
      "total": 5
    }
  }
}

item.charged_back means a provider dispute caused money to be withdrawn. It replaces item.refunded for chargebacks; genuine refunds continue to emit item.refunded. A chargeback withdrawal also emits invoice.updated for the changed invoice state.

Reinstatements, including a Stripe win or funds reinstatement and PayPal chargeback_reimbursement, restore the invoice through invoice.updated only. They emit no second item.charged_back and no item.refunded.

This contract applies prospectively. It does not reclassify or replay historical transaction rows.

Together, the item events represent purchases, genuine refunds, and provider-dispute withdrawals as distinct financial events.

Invoice Events

`invoice.created`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a0b",
  "eventVersion": "v1",
  "objectType": "invoice",
  "eventType": "invoice.created",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "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": 24,
    "total": 24,
    "metadata": {
      "source": "checkout-subscription"
    }
  },
  "invoice": {
    "id": "7bb5ce14-59e0-41ee-8fb7-84d6967cdb68",
    "invoiceNumber": "FLO-1001",
    "state": "open",
    "billingReason": "subscription_cycle",
    "currency": "GBP",
    "amountDue": 22,
    "amountPaid": 0,
    "subtotal": 22,
    "total": 22,
    "paidAt": null,
    "hostedInvoiceUrl": "https://example.com/invoice",
    "invoicePdfUrl": "https://example.com/invoice.pdf",
    "invoiceDetails": {
      "gatewayEventType": "invoice.created",
      "invoiceId": "in_123",
      "invoiceStatus": "open",
      "billingReason": "subscription_cycle",
      "currency": "GBP",
      "amountDue": 22,
      "amountPaid": 0,
      "total": 22
    }
  }
}

`invoice.updated`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a0c",
  "eventVersion": "v1",
  "objectType": "invoice",
  "eventType": "invoice.updated",
  "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": "open",
    "billingReason": "subscription_cycle",
    "currency": "GBP",
    "amountDue": 24,
    "amountPaid": 0,
    "subtotal": 24,
    "total": 24,
    "paidAt": null,
    "hostedInvoiceUrl": "https://example.com/invoice",
    "invoicePdfUrl": "https://example.com/invoice.pdf",
    "invoiceDetails": {
      "gatewayEventType": "invoice.updated",
      "invoiceId": "in_123",
      "invoiceStatus": "open",
      "billingReason": "subscription_cycle",
      "currency": "GBP",
      "amountDue": 24,
      "amountPaid": 0,
      "total": 24
    }
  }
}

`invoice.deleted`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a0d",
  "eventVersion": "v1",
  "objectType": "invoice",
  "eventType": "invoice.deleted",
  "user": {
    "id": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
    "clientUserId": "user_123",
    "email": "user@example.com"
  },
  "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"
    }
  },
  "invoice": {
    "id": "7bb5ce14-59e0-41ee-8fb7-84d6967cdb68",
    "invoiceNumber": "FLO-1001",
    "state": "open",
    "billingReason": "subscription_cycle",
    "currency": "GBP",
    "amountDue": 22,
    "amountPaid": 0,
    "subtotal": 22,
    "total": 22,
    "paidAt": null,
    "hostedInvoiceUrl": "https://example.com/invoice",
    "invoicePdfUrl": "https://example.com/invoice.pdf",
    "invoiceDetails": {
      "gatewayEventType": "invoice.deleted",
      "invoiceId": "in_123",
      "invoiceStatus": "open",
      "billingReason": "subscription_cycle",
      "currency": "GBP",
      "amountDue": 22,
      "amountPaid": 0,
      "total": 22
    }
  }
}

`invoice.paid`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a0e",
  "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
    }
  }
}

`invoice.overdue`

{
  "eventId": "9f6f8b54-8e2d-4f15-8c8a-d7b6d9f41a0f",
  "eventVersion": "v1",
  "objectType": "invoice",
  "eventType": "invoice.overdue",
  "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": "pastDue",
    "billingReason": "subscription_cycle",
    "currency": "GBP",
    "amountDue": 22,
    "amountPaid": 0,
    "subtotal": 22,
    "total": 22,
    "paidAt": null,
    "hostedInvoiceUrl": "https://example.com/invoice",
    "invoicePdfUrl": "https://example.com/invoice.pdf",
    "invoiceDetails": {
      "gatewayEventType": "invoice.overdue",
      "invoiceId": "in_123",
      "invoiceStatus": "open",
      "billingReason": "subscription_cycle",
      "transactionId": "pi_123",
      "currency": "GBP",
      "amountDue": 22,
      "amountPaid": 0,
      "total": 22
    }
  }
}

This event indicates that Flo still considers the invoice collectible, but it is now overdue.

Events

On this page