What's new?
You can now filter events by value and by date, using three new query parameters.
/eventsReturn entities that contain the value specified. Pass a Paddle ID or email address that appears in the event payload, or part of one
Return entities from a specific time. Pass an RFC 3339 datetime string
Return entities up to a specific time. Pass an RFC 3339 datetime string
At the same time, the filter parameter on notifications matches more criteria than it used to. Previously it only accepted a complete transaction, customer, or subscription ID. It can now filter by the ID of any entity that appears in an event, by email addresses, or by partial values.
How it works
When something notable occurs in your system, Paddle creates an event entity with information about what happened. You can subscribe to events via webhooks, or you can query the event stream by sending a GET request to the /events endpoint.
You can now filter the event stream using new filter, to, and from query parameters. When filtering using the filter query parameter, Paddle includes every Paddle ID in an event payload and every email address.
This means you don't need to know which entity an identifier belongs to. Searching for a customer ID returns events for that customer and events for their subscriptions, transactions, and adjustments, because the customer ID appears in all of them.
We also ported this change to the filter query parameter that you can use when listing notifications, too.
Matching
How Paddle matches depends on what you pass:
| You pass | Paddle matches |
|---|---|
| A complete Paddle ID or an email address | The exact value |
The start of a Paddle ID, like ctm_01h84 | Values that begin with it |
| Anything else | Paddle IDs or email addresses that contain it |
Partial values must be at least three characters. Shorter values return a 400 error. Matching isn't case-sensitive.
Dates
from and to take RFC 3339 datetime strings and bound results by when Paddle recorded the event. Both are exclusive, so an event recorded at exactly the time you pass isn't returned.
Examples
This example returns every event that mentions a customer, including events for their subscriptions and transactions.
/events?filter=ctm_01h8441jn5pcwrfhwh78jqt8hkReturn entities that contain the value specified
This example returns events that contain a customer's email address.
/events?filter=ronaldo.zambrano%40example.comReturn entities that contain the value specified
This example returns events that Paddle recorded during August 2026.
/events?from=2026-08-01T00:00:00Z&to=2026-09-01T00:00:00ZReturn entities from a specific time. Pass an RFC 3339 datetime string
Return entities up to a specific time. Pass an RFC 3339 datetime string
You can combine the new parameters with event_type. This example returns transaction.completed events for a subscription in August 2026.
/events?filter=sub_01h04vsc0qhwtsbsxp3rsfsd4p&event_type=transaction.completed&from=2026-08-01T00:00:00Z&to=2026-09-01T00:00:00ZReturn entities that contain the value specified
Return events that match the specified event type
Return entities from a specific time. Pass an RFC 3339 datetime string
Return entities up to a specific time. Pass an RFC 3339 datetime string
Next steps
This change is available in version 1 of the Paddle API.
It's a non-breaking change, meaning it doesn't impact existing integrations. Filters that worked before still return the same results, though when filtering notifications you may now see more results than before.
Paddle retains events for 90 days, so filtering only returns events from that window.
You can list events or list notifications using the API to start using the new query parameters.
Summary of changes
List events
OperationReturn events that contain a Paddle ID, email address, or partial value.
Return events from a specific time.
Return events up to a specific time.
List notifications
OperationNow matches any Paddle ID in an event, email addresses, and partial values.