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.

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