Events

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

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 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.
`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.

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

`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"
  }
}

These events represent one-off purchases, invoice line purchases, and refunds.

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