---
title: "Change URL, online/offline status, billed key, chains or confirmation depths."
method: PATCH
path: "/push/subscriptions/{subscription_id}"
tags: ["Subscriptions"]
---

# Change URL, online/offline status, billed key, chains or confirmation depths.

`PATCH /push/subscriptions/{subscription_id}`

## Request

- Base URL: `https://api.blockvectra.com/v1`
- URL: `https://api.blockvectra.com/v1/push/subscriptions/{subscription_id}`
- Auth: API key in header `x-api-key`

JSON Merge Patch keyed by chain. An object adds a chain or changes its confirmations;
null removes it. An existing chain with omitted confirmations keeps its value, a new
chain uses its default. Repeating the patch changes nothing. Removing the last chain
is 422 chains_required. key_id must be another active key of the same account.
The response includes change_version; compare it with applied_version.

## Request body

- SubscriptionPatch
  - `url` string: https, port 443, a host name (no IP literal), no userinfo or fragment; stored and returned normalized.
  - `status` 'online' | 'offline'
  - `key_id` string
  - `chains` object: Merge patch keyed by chain: an object adds the chain or changes its N, null removes it.

## Response `200`

The subscription after the patch, with the version of this change.

- SubscriptionPatched
  - `id` integer, required: The subscription id: the one number that identifies a subscription everywhere (PostgreSQL integer identity, fits u32, never reused). A plain JSON integer in bodies, decimal digits in the path.
  - `url` string, required: https, port 443, a host name (no IP literal), no userinfo or fragment; stored and returned normalized.
  - `status` 'online' | 'offline', required: online listens and delivers; offline does not listen (addresses unloaded, no matching, delivery or address fee) and keeps its whole configuration, and can go online again at any time. Change it with PATCH; the system also sets offline when the subscription expires (a chain failed for the expiry window, currently 7 days, and no other chain delivered inside it).
  - `key_id` string, required
  - `address_count` integer, required: Distinct addresses of this subscription; additions cannot exceed 1,000,000. Existing oversized subscriptions can remove addresses and resend existing addresses.
  - `applied_version` integer, required: Address and chain changes of this subscription up to this version are applied on every chain; compare with change_version returned by add, remove and PATCH (a counter of this subscription only).
  - `chains` object, required
  - `created_at` string, required

## Other responses

- `default`: Error envelope; the codes, statuses and retry rules are in root x-push-errors. 429 and 503 carry Retry-After.

---

[API](https://skmtc.dev/blockvectra/apis/blockvectra-push-api.md) · [All operations](https://skmtc.dev/blockvectra/apis/blockvectra-push-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blockvectra/apis/blockvectra-push-api/revisions/396dd7621c54?raw)