---
title: "Create a subscription"
method: POST
path: "/v3/subscriptions"
tags: ["subscriptions"]
---

# Create a subscription

`POST /v3/subscriptions`

## Request

- Base URL: `https://gateway.stage.bill.com/connect-events`
- URL: `https://gateway.stage.bill.com/connect-events/v3/subscriptions`
- Auth: none declared. Required headers: `X-Idempotent-Key`

Create a new event subscription. You can subscribe to multiple events with a single request. You can create up to 10 webhook subscriptions per organization.

BILL provides a full catalog of all the events that you can subscribe to with `GET /v3/events/catalog`. See [Get events catalog](ref:geteventcatalog) in the API reference for more information.

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

## Headers

- `X-Idempotent-Key` string, required
- `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.

## Request body

- SubscriptionRequestDto: Create a subscription
  - `name` string, required: Subscription name
  - `status` object, required: Subscription status information
    - `enabled` boolean: Set as `true` if the subscription is enabled. When you create a new subscription, this value is set as `true` by default.
    - `reason` string: Reason for changing the subscription status. This field is used by BILL for informing you when the `enabled` field is set as `false`.
  - `events` SubscriptionEventDto[], required: Subscription events information. You can retrieve event `type` and `version` with `GET /v3/events/catalog`.
    - `type` string, required: Event type
    - `version` string, required: Event type version
  - `notificationUrl` string, required: Event notification URL. The URL must be HTTPS. BILL uses this URL to send you event notifications.

## Response `200`

createSubscription 200 response

- SubscriptionWithSecurityKeyResponseDto: Subscription and security key information.
  - `id` string: BILL-generated ID of the subscription
  - `name` string: Subscription name
  - `organizationId` string: BILL-generated ID of the organization. BILL sends you event notifications only for the BILL organization used to set up a subscription.
  - `status` object: Subscription status information
    - `enabled` boolean: Set as `true` if the subscription is enabled. When you create a new subscription, this value is set as `true` by default.
    - `reason` string: Reason for changing the subscription status. This field is used by BILL for informing you when the `enabled` field is set as `false`.
    - `actor` 'CLIENT' | 'SYSTEM': Entity that set the subscription status
  - `events` SubscriptionEventDto[]: Subscription events information. You can retrieve event `type` and `version` with `GET /v3/events/catalog`.
    - `type` string, required: Event type
    - `version` string, required: Event type version
  - `notificationUrl` string: Event notification URL. The URL must be HTTPS. BILL uses this URL to send you event notifications.
  - `createdTime` string, date-time: Subscription created date and time
  - `updatedTime` string, date-time: Subscription updated date and time
  - `securityKey` string: BILL-generated security key. When you create a new subscription, a one-time `securityKey` is generated and all event notifications sent to your `notificationUrl` are signed with this key.

---

[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)