---
title: "Get list of event notifications"
method: GET
path: "/v3/events/subscription/{subscriptionId}"
tags: ["events"]
---

# Get list of event notifications

`GET /v3/events/subscription/{subscriptionId}`

## Request

- Base URL: `https://gateway.stage.bill.com/connect-events`
- URL: `https://gateway.stage.bill.com/connect-events/v3/events/subscription/{subscriptionId}`
- Auth: none declared

Get a list of event notifications sent to you for a subscription. You can use this endpoint to address any issues with notification retries.

In the request, set `createdTimeFrom` and `createdTimeTo` to get event notifications for the specified time range. If you do not set `createdTimeTo`, the current date and time is used. By default, you get 20 results on one page of results. Set `max` in your request to get up to 100 results on one page.

**Note**: In this list operation, pagination is available only in one direction. The `nextPage` value is available in the response for you to retrieve the next page of results. However, you cannot retrieve the previous page of results.

See [Webhooks](doc:webhooks) in the Guides section for more information, sample requests, and notification payloads for BILL events.

## Path parameters

- `subscriptionId` string, required: BILL-generated ID of the subscription

## Query parameters

- `entityId` string, nullable: BILL-generated ID of the entity, such as bill or vendor. For example, to filter notifications by a specific bill, set this value as the ID of the bill.
- `max` integer, nullable: Maximum number of results
- `createdTimeFrom` string, nullable: Event notification created start date and time. The value is in the ISO 8601 DateTime (UTC) format. For example, `2026-12-30T00:00:00Z`.
- `createdTimeTo` string, nullable: Event notification created end date and time. The value is in the ISO 8601 DateTime (UTC) format. For example, `2026-12-31T00:00:00Z`. If you do not set `createdTimeTo`, the current date and time is used.
- `ascending` boolean, nullable: Set as `true` to sort event notifications in the ascending order. By default, filtered notifications are sorted in the descending order. **Note**: You must set `createdTimeFrom` for the notifications in the response to be sorted. If you do not set `createdTimeFrom`, the notifications in the response are not sorted.
- `page` string, nullable: Next page of results. When a list has multiple pages, the `nextPage` value in the response enables you to navigate to the next page of results. Set `page` as the `nextPage` value for navigation.

## Headers

- `sessionId` string, nullable: API session ID generated with `/v3/login`
- `devKey` string, nullable: Developer key sent to you by BILL when you create a developer account. Set `sessionId` and `devKey` for organization-level BILL v3 API webhook events.
- `appKey` string, nullable: Application key sent to you by BILL when you create a partner account. Set `sessionId` and `appKey` for partner-level BILL v3 API webhook events.
- `apiToken` string, nullable: Access token for Spend & Expense API authentication. Set `apiToken` for Spend & Expense webhook events.

## Response `200`

getEventsForSubscription 200 response

- ListEventWithRetriesDto: Pagination information.
  - `nextPage` string
  - `results` EventWithRetriesDto[]
    - `id` string: BILL-generated ID of the event
    - `type` string: Event type
    - `version` string: Event type version
    - `subscriptionId` string: BILL-generated ID of the subscription
    - `payload` string: Event payload. The payload is JSON escaped and presented as a string.
    - `createdTime` string, date-time: Event created date and time
    - `statusCode` integer: HTTP status code received from the notification URL
    - `retries` EventRetryDto[]: Event retries information
      - `attemptNumber` integer: Event notification retry attempt number
      - `createdTime` string, date-time: Event notification retry created date and time
      - `statusCode` integer: HTTP status code received from the notification URL

---

[API](https://skmtc.dev/bill/apis/connect-events-api.md) - [All operations](https://skmtc.dev/bill/apis/connect-events-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bill/apis/connect-events-api/revisions/397b6f4013bc?raw)