Skip to main content
These endpoints exist only when subscription.enabled is true in your plugin configuration. All subscription endpoints require an active session.
The subscriptions endpoints let you upgrade, cancel, pause, resume, update, restore, list, and inspect subscriptions. They are backed by a local subscription table that is kept in sync with Razorpay via webhooks.

Upgrade subscription

POST /api/auth/subscription/upgrade Creates or upgrades a subscription for the authenticated user (or an organization). If a subscription already exists for the same plan, the endpoint returns ALREADY_SUBSCRIBED_PLAN. When a free trial is configured on the plan and the reference has never had a trial, the subscription starts after the trial period. Server API name: upgradeSubscription
Client method: authClient.subscription.upgrade(...)
string
required
Plan name to upgrade to. Matched case-insensitively against the configured plans.
string
The reference id to attach the subscription to. Defaults to the active organization id when customerType is organization, or the user id otherwise.
string
default:"user"
Either user or organization.
boolean
default:"false"
Use the plan’s annualPlanId instead of the regular planId.
object
Arbitrary metadata stored on the local subscription row.
array
Add-on line items to include at creation. Each item: { item_id: string, quantity?: number }.
boolean
default:"false"
When true, schedules the upgrade to take effect at the current cycle end (schedule_change_at: "cycle_end").
object
The local subscription row.
object
The Razorpay subscription object.
string
Hosted authorization link for the customer to complete payment.
Errors: SUBSCRIPTION_PLAN_NOT_FOUND, CUSTOMER_NOT_FOUND, ALREADY_SUBSCRIBED_PLAN, SUBSCRIPTION_UPDATE_FAILED, EMAIL_VERIFICATION_REQUIRED, FORBIDDEN, UNAUTHORIZED, REFERENCE_ID_NOT_ALLOWED, ORGANIZATION_REFERENCE_ID_REQUIRED.

Cancel subscription

POST /api/auth/subscription/cancel Cancels the active subscription for the authenticated reference. By default the cancellation is immediate. Pass cancelAtCycleEnd: true to let the subscription run until the end of the current billing cycle. Server API name: cancelSubscription
Client method: authClient.subscription.cancel(...)
string
Reference id. Defaults to the active organization id or the user id.
string
default:"user"
Either user or organization.
boolean
default:"false"
When true, the subscription remains active until the current cycle ends and cancelAtCycleEnd is set to true locally.
object
The updated local subscription row.
Errors: SUBSCRIPTION_NOT_FOUND, SUBSCRIPTION_ALREADY_CANCELLED, SUBSCRIPTION_CANCEL_FAILED.

Pause subscription

POST /api/auth/subscription/pause Pauses an active subscription. The subscription must be active and not already paused. Server API name: pauseSubscription
Client method: authClient.subscription.pause(...)
string
Reference id. Defaults to the active organization id or the user id.
string
default:"user"
Either user or organization.
string
default:"now"
When to pause. Only "now" is supported.
object
The updated local subscription row with status paused.
Errors: SUBSCRIPTION_NOT_ACTIVE, SUBSCRIPTION_ALREADY_PAUSED, SUBSCRIPTION_PAUSE_FAILED.

Resume subscription

POST /api/auth/subscription/resume Resumes a paused subscription. The subscription must be paused. Server API name: resumeSubscription
Client method: authClient.subscription.resume(...)
string
Reference id. Defaults to the active organization id or the user id.
string
default:"user"
Either user or organization.
string
default:"now"
When to resume. Only "now" is supported.
object
The updated local subscription row with status active.
Errors: SUBSCRIPTION_NOT_PAUSED, SUBSCRIPTION_RESUME_FAILED.

Update subscription

POST /api/auth/subscription/update Updates an existing subscription. You can change the plan, quantity, offer, schedule, and metadata. Server API name: updateSubscription
Client method: authClient.subscription.update(...)
string
Reference id. Defaults to the active organization id or the user id.
string
default:"user"
Either user or organization.
string
New Razorpay plan id to switch to.
string
Razorpay offer id to apply.
integer
New seat quantity.
integer
New remaining billing cycle count.
integer
Unix timestamp for when the update should take effect.
string
"now" or "cycle_end". When "cycle_end", the change is deferred.
boolean
Whether Razorpay should notify the customer.
object
Metadata to merge into the subscription.
object
The updated local subscription row.
object
The updated Razorpay subscription object.
Errors: SUBSCRIPTION_UPDATE_FAILED.

Restore subscription

POST /api/auth/subscription/restore Restores a subscription that is scheduled to cancel at the end of the current cycle. This clears the local cancelAtCycleEnd flag. Razorpay does not expose a native restore API, so the plugin only updates the local row. Server API name: restoreSubscription
Client method: authClient.subscription.restore(...)
string
Reference id. Defaults to the active organization id or the user id.
string
default:"user"
Either user or organization.
object
The updated local subscription row.
Errors: SUBSCRIPTION_NOT_PENDING_CANCEL, SUBSCRIPTION_RESTORE_FAILED.

List subscriptions

GET /api/auth/subscription/list Lists local subscriptions for the authenticated reference. Server API name: listSubscriptions
Client method: authClient.subscription.list({ query: { ... } })
string
Reference id. Defaults to the active organization id or the user id.
string
default:"user"
Either user or organization.
array
Array of local subscription rows.

Get subscription

GET /api/auth/subscription/get Retrieves a single local subscription by its local id. Server API name: getSubscription
Client method: authClient.subscription.get({ query: { ... } })
string
required
Local subscription id.
string
Reference id. Defaults to the active organization id or the user id.
string
default:"user"
Either user or organization.
object
The local subscription row.

List Razorpay subscriptions

GET /api/auth/razorpay/subscription/list Lists subscriptions directly from Razorpay with pagination and optional filters. This endpoint is always available regardless of the local subscription table. Server API name: fetchAllSubscriptions
Client method: authClient.razorpay.subscription.list({ query: { ... } })
integer
Unix timestamp. Return subscriptions created after this time.
integer
Unix timestamp. Return subscriptions created before this time.
integer
Maximum number of subscriptions to return. Maximum value is 100.
integer
Number of subscriptions to skip.
string
Filter by Razorpay plan id.
string
Filter by status: created, authenticated, active, pending, halted, paused, cancelled, reverted, expired, or completed.
string
Comma-separated list of related resources to expand.
Errors: SUBSCRIPTION_LIST_FAILED.