---
title: "Update a subscription"
method: PATCH
path: "/subscriptions/{id}"
tags: ["Subscriptions"]
---

# Update a subscription

`PATCH /subscriptions/{id}`

Update plan, quantity, or schedule future changes for a subscription. Use schedule_change_at='now' for immediate effect (creates a new billing cycle) or 'cycle_end' to defer until the current cycle ends. Cannot change plan mid-cycle without creating a new cycle.

## Path parameters

- `id` string, required

## Request body

- object
  - `plan_id` string — New plan ID to switch to.
  - `quantity` integer
  - `remaining_count` integer — Override remaining billing cycles.
  - `schedule_change_at` 'now' | 'cycle_end' — When changes take effect. 'now' starts a new cycle immediately; 'cycle_end' defers to end of current cycle.
  - `customer_notify` 0 | 1
  - `notes` Notes — Key-value pairs for storing custom metadata. Maximum 15 pairs. Each key and value must not exceed 256 characters.

## Response `200`

Subscription updated.

- Subscription — A recurring billing subscription linking a customer to a plan. Requires customer mandate authorization via short_url before charges can be collected.
  - `id` string — Subscription ID. Prefix: sub_
  - `entity` 'subscription'
  - `plan_id` string — Associated plan ID (plan_*).
  - `status` 'created' | 'authenticated' | 'active' | 'pending' | 'halted' | 'cancelled' | 'completed' | 'expired' | 'paused' — Subscription lifecycle status. created→authenticated (mandate authorized)→active→completed/cancelled/expired. pending=charge retry scheduled; halted=multiple failures; paused=temporarily stopped.
  - `current_start` integer — Unix timestamp of current billing cycle start.
  - `current_end` integer — Unix timestamp of current billing cycle end.
  - `ended_at` integer — Unix timestamp when subscription ended (cancelled/completed/expired).
  - `quantity` integer — Number of plan units billed per cycle.
  - `notes` Notes — Key-value pairs for storing custom metadata. Maximum 15 pairs. Each key and value must not exceed 256 characters.
  - `charge_at` integer — Unix timestamp of next scheduled charge attempt.
  - `start_at` integer — Unix timestamp of first charge. Defaults to subscription creation time.
  - `end_at` integer — Unix timestamp after which no more charges will be attempted.
  - `auth_attempts` integer — Number of mandate authorization attempts.
  - `total_count` integer — Total billing cycles. 0 = indefinite.
  - `paid_count` integer — Number of billing cycles successfully charged.
  - `remaining_count` integer — Remaining billing cycles.
  - `customer_notify` 0 | 1 — 1 = Razorpay sends SMS/email notifications to customer on each charge.
  - `short_url` string — Mandate authorization URL. Must be sent to the customer to activate the subscription.
  - `has_scheduled_changes` boolean — True if a plan/quantity change is scheduled for the next cycle.
  - `change_scheduled_at` 'now' | 'cycle_end' — When scheduled changes take effect.
  - `source` string — Source that created the subscription (e.g., api, dashboard).
  - `offer_id` string — Offer/coupon applied to the subscription.
  - `expire_by` integer — Unix timestamp by which the customer must authorize the mandate.
  - `created_at` integer

## Other responses

- `400` — Bad request. Invalid parameters or missing required fields.
- `401` — Authentication failed. Invalid or missing API key credentials.
- `404` — Resource not found.
- `429` — Rate limit exceeded. Implement exponential backoff with jitter before retrying.

---

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