list_notifications
Retrieve and filter notification records from Paddle Billing to monitor delivery status, debug issues, and track event-based alerts with pagination and search capabilities.
Instructions
This tool will list notifications in Paddle.
When an event that has a notification destination occurs, Paddle creates a notification entity with information about the notification.
A single event might create multiple notifications. This is common when working with multiple notification destinations that are subscribed to the same events. When an event occurs, Paddle creates a separate notification entity for each notification destination. They'll share the same eventId, but have different notificationId.
Notifications older than 90 days aren't retained and won't be returned.
Use the maximum perPage by default (200) to ensure comprehensive results. Filter notifications by notificationSettingId, search (fuzzy search on the event's type or id), status, filter (pass a transaction, customer, or subscription ID), to, and from as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.
Check the following details to understand the success or failure of the notification delivery according to Paddle and debug issues:
status: Status of the notification.
notAttempted: Paddle hasn't yet tried to deliver this notification.
needsRetry: Paddle tried to deliver this notification, but it failed. It's scheduled to be retried.
delivered: Paddle delivered this notification successfully.
failed: Paddle tried to deliver this notification, but all attempts failed. It's not scheduled to be retried.
origin: Describes how this notification was created.
event: Notification created when a subscribed event occurred.
replay: Notification created when a notification with the origin event was replayed.
deliveredAt: RFC 3339 datetime string of when this notification was delivered. null if not yet delivered successfully.
lastAttemptAt: RFC 3339 datetime string of when this notification was last attempted.
retryAt: RFC 3339 datetime string of when this notification is scheduled to be retried.
timesAttempted: How many times delivery of this notification has been attempted.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Return entities after the specified Paddle ID when working with paginated endpoints. | |
| notificationSettingId | No | Return entities related to the specified notification destination. Use a comma-separated list to specify multiple notification destination IDs. | |
| orderBy | No | Order returned entities by the specified field and direction. | |
| perPage | No | Set how many entities are returned per page. Returns the maximum number of results if a number greater than the maximum is requested. | |
| search | No | Return entities that match a search query. Pass an exact match for the Paddle ID or event type. | |
| status | No | Return entities that match the specified status. Use a comma-separated list to specify multiple status values. | |
| filter | No | Return entities that contain the Paddle ID specified. Pass a transaction, customer, or subscription ID. | |
| to | No | Return entities up to a specific time. Pass an RFC 3339 datetime string. | |
| from | No | Return entities from a specific time. Pass an RFC 3339 datetime string. |
Implementation Reference
- src/functions.ts:512-524 (handler)The core handler function `listNotifications` that executes the tool logic by calling `paddle.notifications.list(params)` and returning paginated notifications.
export const listNotifications = async ( paddle: Paddle, params: z.infer<typeof Parameters.listNotificationsParameters>, ) => { try { const collection = paddle.notifications.list(params); const notifications = await collection.next(); const pagination = paginationData(collection); return { pagination, notifications }; } catch (error) { return error; } }; - src/tools.ts:757-768 (registration)Registration of the 'list_notifications' tool in the tools array, specifying method, name, description, parameters schema reference, and required actions.
{ method: "list_notifications", name: "List notifications", description: prompts.listNotificationsPrompt, parameters: params.listNotificationsParameters, actions: { notifications: { read: true, list: true, }, }, }, - src/api.ts:51-51 (registration)Mapping of TOOL_METHODS.LIST_NOTIFICATIONS to the listNotifications handler function in the toolMap used by PaddleAPI to execute tools.
[TOOL_METHODS.LIST_NOTIFICATIONS]: funcs.listNotifications, - src/constants.ts:43-43 (registration)Definition of the LIST_NOTIFICATIONS constant string used as the tool method identifier.
LIST_NOTIFICATIONS: "list_notifications",