> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay-881012b3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a Subscription

> Update a Subscription using the Razorpay API.

<div style={{display:"flex",flexWrap:"wrap",alignItems:"center",gap:"0.35rem 0.9rem",border:"1px solid rgba(128,128,128,0.28)",borderRadius:"0.5rem",padding:"0.45rem 0.75rem",margin:"0 0 1.25rem",fontSize:"0.875rem"}}>
  <span style={{fontWeight:600}}>Available in</span>
  <span>🇮🇳 India</span>
  <span>🇸🇬 Singapore</span>
  <span>🇺🇸 United States</span>
</div>

Use this endpoint to update a Subscription.

<RequestExample>
  ```bash Curl theme={null}
  curl -u <YOUR_KEY>:<YOUR_SECRET> \
  -X PATCH https://api.razorpay.com/v1/subscriptions/sub_00000000000001 \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id":"plan_00000000000002",
    "offer_id":"offer_JHD834hjbxzhd38d",
    "quantity":5,
    "remaining_count":5,
    "start_at":1496000432,
    "schedule_change_at":"now",
    "customer_notify": true
  }'
  ```

  ```java Java theme={null}
  RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

  String subscriptionId = "sub_00000000000002";

  JSONObject params = new JSONObject();
  params.put("plan_id","plan_00000000000002");
  params.put("offer_id","offer_JHD834hjbxzhd38d");
  params.put("quantity",5);
  params.put("remaining_count",5);
  params.put("start_at",1496000432);
  params.put("schedule_change_at","now");
  params.put("customer_notify", true);

  Subscription subscription = razorpay.subscription.update(subscriptionId,params);
  ```

  ```php PHP theme={null}
  $api = new Api($key_id, $secret);

  $api->subscription->fetch($subscriptionId)->update($options);
  ```

  ```javascript Node.js theme={null}
  var instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' })

  instance.subscriptions.update(subscriptionId,options)
  ```

  ```python Python theme={null}
  import razorpay
  client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET"))

  client.subscription.update(subscriptionId, options)
  ```

  ```ruby Ruby theme={null}
  require "razorpay"
  Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET')

  subscriptionId = "sub_00000000000002"

  options = {
    "plan_id":"plan_00000000000002",
    "offer_id":"offer_JHD834hjbxzhd38d",
    "quantity":5,
    "remaining_count":5,
    "start_at":1496000432,
    "schedule_change_at":"now",
    "customer_notify":1
  }

  Razorpay::Subscription.fetch(subscriptionId).edit(options)
  ```

  ```go Go theme={null}
  import ( razorpay "github.com/razorpay/razorpay-go" )
  client := razorpay.NewClient("YOUR_KEY_ID", "YOUR_SECRET")

  body, err := client.Subscription.Update("<subscriptionId>", options, nil)
  ```

  ```csharp .NET theme={null}
  RazorpayClient client = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");

  string subscriptionId = "sub_00000000000002";

  Dictionary<string, object> param = new Dictionary<string, object>();
  param.Add("plan_id","plan_00000000000002");
  param.Add("offer_id","offer_JHD834hjbxzhd38d");
  param.Add("quantity",5);
  param.Add("remaining_count",5);
  param.Add("start_at",1496000432);
  param.Add("schedule_change_at","now");
  param.Add("customer_notify", true);

  Subscription subscription = client.Subscription.Fetch(subscriptionId).Edit(param);
  ```

  ```bash CLI theme={null}
  razorpay subscriptions update sub_ABC123 \
    --plan-id plan_XYZ456 \
    --quantity 2 \
    --remaining-count 5 \
    --schedule-change-at cycle_end \
    --customer-notify
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "id":"sub_00000000000002",
    "entity":"subscription",
    "plan_id":"plan_00000000000002",
    "customer_id":"cust_00000000000002",
    "status":"authenticated",
    "current_start":null,
    "current_end":null,
    "ended_at":null,
    "quantity":3,
    "notes":{
      "notes_key_1":"Tea, Earl Grey, Hot",
      "notes_key_2":"Tea, Earl Grey… decaf."
    },
    "charge_at":1580453311,
    "start_at":1580453311,
    "end_at":1606588200,
    "auth_attempts":0,
    "total_count":6,
    "paid_count":0,
    "customer_notify":true,
    "created_at":1580283807,
    "expire_by":1580626111,
    "short_url":"https://rzp.io/i/yeDkUKy",
    "has_scheduled_changes":false,
    "change_scheduled_at":null,
    "source": "api",
    "offer_id":"offer_JHD834hjbxzhd38d",
    "remaining_count":6
  }
  ```

  ```json Failure theme={null}
  {
    "error": {
      "code": "BAD_REQUEST_ERROR",
      "description": "subscriptions cannot be updated when payment mode is UPI"
    }
  }
  ```
</ResponseExample>

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier linked to a Subscription. For example, `sub_00000000000001`.
</ParamField>

## Request Parameters

<ParamField body="plan_id" type="string">
  The unique identifier of the new plan that should be linked to the Subscription. For example, `plan_00000000000001`.
</ParamField>

<ParamField body="offer_id" type="string">
  The unique identifier of the offer that should be linked to the Subscription. You can obtain this from the Dashboard. For example, `offer_JHD834hjbxzhd38d`.
</ParamField>

<ParamField body="quantity" type="integer">
  The number of times the plan should be linked to the Subscription. For example, if the plan is ₹100/user/month and the customer has 5 users, you should pass `5` as the quantity to have the customer charged ₹500 (5 x ₹100) monthly. By default, this value is set to `1`.
</ParamField>

<ParamField body="remaining_count" type="integer">
  This parameter is used to update the `total_count` for a Subscription. For example, let us consider a monthly Subscription with 12 billing cycles. The Subscription has been charged successfully 4 times and 3 more invoices have been issued, but have not been charged. The remaining count in such cases is 5. However, you can overwrite this value using this parameter.
</ParamField>

<ParamField body="start_at" type="integer">
  Unix timestamp. The new start date for the Subscription.
</ParamField>

<ParamField body="schedule_change_at" type="string">
  Represents when the Subscription should be updated.

  * `now` (default): Updates the Subscription immediately.
  * `cycle_end`: Updates the Subscription at the end of the current billing cycle.
</ParamField>

<ParamField body="customer_notify" type="boolean">
  Represents who sends notifications to the customer. Possible values:

  * `true` (default): Notifications sent by Razorpay.
  * `false`: Notifications sent by you.
</ParamField>

## Response Parameters

<ResponseField name="id" type="string">
  The unique identifier of the subscription created. For example, `sub_00000000000001`.
</ResponseField>

<ResponseField name="entity" type="string">
  The entity being created. Here, it will be `subscription`.
</ResponseField>

<ResponseField name="plan_id" type="string">
  The unique identifier for a plan that is linked to the created subscription. For example, `plan_00000000000001`.
</ResponseField>

<ResponseField name="customer_id" type="string">
  The unique identifier of the customer linked to the subscription. This is populated automatically once the customer completes the authorisation transaction. For example, `cust_00000000000001`.
</ResponseField>

<ResponseField name="status" type="string">
  Status of the subscription. Refer to the [life cycle section](/docs/us/payments/subscriptions/states) for more details. Possible values:

  * `created`
  * `authenticated`
  * `active`
  * `pending`
  * `halted`
  * `cancelled`
  * `completed`
  * `expired`
</ResponseField>

<ResponseField name="current_start" type="integer">
  Unix timestamp. The start time of the current billing cycle of the subscription. For example, `1581013800`.
</ResponseField>

<ResponseField name="current_end" type="integer">
  Unix timestamp. The end time of the current billing cycle of the subscription. For example, `1581013800`.
</ResponseField>

<ResponseField name="ended_at" type="integer">
  The timestamp, in Unix format, when the subscription was completed or was cancelled. For example, `1581013800`.
</ResponseField>

<ResponseField name="quantity" type="integer">
  The number of times the plan should be linked to the subscription. For example, if the plan is ₹100/user/month and the customer has 5 users, you should pass 5 as the quantity to have the customer charged ₹500 (5 x ₹100) monthly. By default, this value is set to 1.
</ResponseField>

<ResponseField name="notes" type="object">
  Notes you can enter for the contact for future reference. This is a key-value pair. You can enter a maximum of 15 key-value pairs. For example, `"note_key": "Beam me up Scotty”`.
</ResponseField>

<ResponseField name="charge_at" type="integer">
  Unix timestamp. This indicates when the next charge on the subscription should be made. For example, `1581013800`.
</ResponseField>

<ResponseField name="offer_id" type="string">
  The unique identifier of the offer that should be linked to the subscription. For example, `offer_JHD834hjbxzhd38d`.
</ResponseField>

<ResponseField name="start_at" type="integer">
  The timestamp, in Unix format, when the subscription should start. If not passed, the subscription starts immediately after the authorisation payment. For example, `1581013800`.
</ResponseField>

<ResponseField name="end_at" type="integer">
  The timestamp, in Unix format, when the subscription should end. For example, `1581013800`.
</ResponseField>

<ResponseField name="auth_attempts" type="integer">
  The number of times that the charge for the current billing cycle has been attempted on the card. For example, `2`.
</ResponseField>

<ResponseField name="total_count" type="integer">
  The number of billing cycles for which the customer should be charged. For example, `2`. We support subscriptions for a maximum duration of 100 years. The number of billing cycles depends if the subscription is daily, weekly, monthly or yearly.
</ResponseField>

<ResponseField name="paid_count" type="integer">
  This indicates the number of billing cycles for which the customer has already been charged. For example, `2`.
</ResponseField>

<ResponseField name="customer_notify" type="boolean">
  Indicates whether the communication to the customer would be handled by businesses or Razorpay.

  * `true`: Communication handled by Razorpay. Defaults to `true`.
  * `false`: Communication handled by businesses.
</ResponseField>

<ResponseField name="created_at" type="integer">
  The timestamp, in Unix format, when the subscription was created. For example, `1581013800`.
</ResponseField>

<ResponseField name="expire_by" type="integer">
  The timestamp, in Unix format, till when the customer can make the authorisation payment. For example, `1581013800`.
</ResponseField>

<ResponseField name="short_url" type="string">
  URL that can be used to make the authorisation payment. For example, `https://rzp.io/i/PWtAiEo`.
</ResponseField>

<ResponseField name="has_scheduled_changes" type="boolean">
  Indicates if the subscription has any scheduled changes. Possible values:

  * `true`: Subscription has scheduled changes.
  * `false`: Subscription does not have scheduled changes.
</ResponseField>

<ResponseField name="schedule_change_at" type="string">
  Represents when the subscription should be updated. Possible values:

  * `now` (default): Updates the subscription immediately.
  * `cycle_end`: Updates the subscription at the end of the current billing cycle.
</ResponseField>

<ResponseField name="remaining_count" type="integer">
  This indicates the number of billing cycles remaining on the subscription. For example, `2`.
</ResponseField>

## Errors

<AccordionGroup>
  <Accordion title="Subscriptions cannot be updated when payment mode is UPI">
    **Code:** `400`

    This error occurs when you are trying to update a Subscription authorised via UPI.

    **Solution:** You cannot update a Subscription authorised via UPI mode or Emandate.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Can't update Subscription when Subscription is not in Authenticated or Active state">
    **Code:** `400`

    This error occurs when you are trying to update a Subscription in the created state.

    **Solution:** Ensure that the Subscription status is either in the authenticated or active state.
  </Accordion>

  <Accordion title="Parameters to update can't be empty.">
    **Code:** `400`

    The PATCH request body is empty. At least one updatable field must be provided.

    **Solution:** Include at least one of the updatable fields (`plan_id`, `quantity`, `remaining_count`, `schedule_change_at`) in the request body.
  </Accordion>

  <Accordion title="The remaining count must be at least 1.">
    **Code:** `400`

    `remaining_count` was passed as `0` or a negative value.

    **Solution:** Pass `remaining_count` as a positive integer.
  </Accordion>

  <Accordion title="{any extra field} is/are not required and should not be sent.">
    **Code:** `400`

    The request body contains fields that are not updatable on a Subscription.

    **Solution:** Only include updatable fields (`plan_id`, `quantity`, `remaining_count`, `schedule_change_at`).
  </Accordion>

  <Accordion title="subscriptions cannot be updated when payment mode is emandate.">
    **Code:** `400`

    The Subscription was authenticated via Emandate. Emandate subscriptions cannot be updated through this API.

    **Solution:** Emandate subscriptions are immutable post-authentication. Cancel and create a new Subscription if changes are needed.
  </Accordion>

  <Accordion title="Request failed because another subscription operation is in progress.">
    **Code:** `400`

    A concurrent update, cancel or pause/resume operation is already running for the same Subscription. Razorpay holds a short-lived lock against the subscription id to prevent state-corruption.

    **Solution:** Wait a few seconds and retry. If the issue persists, fetch the Subscription to confirm its current state before retrying.
  </Accordion>

  <Accordion title="Subscriptions with active offers can only be downgraded at the end of the billing cycle.">
    **Code:** `400`

    A `plan_id` change has been requested that downgrades the Subscription amount, but the Subscription has an active offer attached. Downgrades on offer-linked subscriptions are only allowed at the end of the current billing cycle.

    **Solution:** Pass `schedule_change_at: "cycle_end"` so the downgrade is applied at the end of the current cycle, or remove the offer first.
  </Accordion>
</AccordionGroup>