These endpoints exist only when
subscription.enabled is true in your plugin configuration. All subscription endpoints require an active session.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: upgradeSubscriptionClient method:
authClient.subscription.upgrade(...)
The reference id to attach the subscription to. Defaults to the active organization id when
customerType is organization, or the user id otherwise.When
true, schedules the upgrade to take effect at the current cycle end (schedule_change_at: "cycle_end").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: cancelSubscriptionClient method:
authClient.subscription.cancel(...)
When
true, the subscription remains active until the current cycle ends and cancelAtCycleEnd is set to true locally.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: pauseSubscriptionClient method:
authClient.subscription.pause(...)
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: resumeSubscriptionClient method:
authClient.subscription.resume(...)
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: updateSubscriptionClient method:
authClient.subscription.update(...)
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: restoreSubscriptionClient method:
authClient.subscription.restore(...)
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: listSubscriptionsClient method:
authClient.subscription.list({ query: { ... } })
Get subscription
GET /api/auth/subscription/get
Retrieves a single local subscription by its local id.
Server API name: getSubscriptionClient method:
authClient.subscription.get({ query: { ... } })
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: fetchAllSubscriptionsClient method:
authClient.razorpay.subscription.list({ query: { ... } })
Filter by status:
created, authenticated, active, pending, halted, paused, cancelled, reverted, expired, or completed.Errors:
SUBSCRIPTION_LIST_FAILED.