---
title: "Replace a subscription"
method: PUT
path: "/v3/subscriptions/{subscriptionId}"
tags: ["subscriptions"]
---

# Replace a subscription

`PUT /v3/subscriptions/{subscriptionId}`

Update the events that you are subscribed to.

You can use the PUT operation to add, remove, or replace events in a subscription. For example, you can replace the `bill.created` event with `bill.updated` in your subscription.

## Path parameters

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

## 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.

## 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`

replaceSubscription 200 response

- SubscriptionResponseDto — Subscription response 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

---

[API](https://skmtc.net/bill/apis/bill-v3-api.md) · [All operations](https://skmtc.net/bill/apis/bill-v3-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bill/bill-v3-api/versions/0483350c434e/schema)