Sign in

v1

latestOpenAPI 3.0.0Proprietary2026-07-1313647393.0 KB
Subscriptions

Update a subscription

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.

patch/subscriptions/{id}

Path parameters

idstring required

Subscription ID (sub_*).

Request body

plan_idstring

New plan ID to switch to.

quantityinteger
remaining_countinteger

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_notify0 | 1
notesNotes

Key-value pairs for storing custom metadata. Maximum 15 pairs. Each key and value must not exceed 256 characters.

Response

Subscription updated.

idstring

Subscription ID. Prefix: sub_

entity'subscription'
plan_idstring

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_startinteger

Unix timestamp of current billing cycle start.

current_endinteger

Unix timestamp of current billing cycle end.

ended_atinteger

Unix timestamp when subscription ended (cancelled/completed/expired).

quantityinteger

Number of plan units billed per cycle.

notesNotes

Key-value pairs for storing custom metadata. Maximum 15 pairs. Each key and value must not exceed 256 characters.

charge_atinteger

Unix timestamp of next scheduled charge attempt.

start_atinteger

Unix timestamp of first charge. Defaults to subscription creation time.

end_atinteger

Unix timestamp after which no more charges will be attempted.

auth_attemptsinteger

Number of mandate authorization attempts.

total_countinteger

Total billing cycles. 0 = indefinite.

paid_countinteger

Number of billing cycles successfully charged.

remaining_countinteger

Remaining billing cycles.

customer_notify0 | 1

1 = Razorpay sends SMS/email notifications to customer on each charge.

short_urlstring

Mandate authorization URL. Must be sent to the customer to activate the subscription.

has_scheduled_changesboolean

True if a plan/quantity change is scheduled for the next cycle.

change_scheduled_at'now' | 'cycle_end'

When scheduled changes take effect.

sourcestring

Source that created the subscription (e.g., api, dashboard).

offer_idstring

Offer/coupon applied to the subscription.

expire_byinteger

Unix timestamp by which the customer must authorize the mandate.

created_atinteger