Subscriptions
Learn how to implement recurring billing, check feature access limits, and manage active customer subscription tiers securely via the official SDK.
The Subscriptions Module
The SDK's subscriptions module exposes a suite of high-fidelity methods to check user states and verify access criteria instantly:
typescript
import { settle } from '@/lib/settle'
// 1. Retrieve user's current subscription profile
const profile = await settle.subscriptions.getSubscription('user_998877')
console.log(profile.planName) // e.g. "Growth Premium"
console.log(profile.isActive) // true / false
console.log(profile.endsAt) // Date object of next renewalMethod Reference
#### 1. Check Feature Access
typescript
const access = await settle.subscriptions.checkAccess('user_998877', 'feature_gpt4')
if (access.hasAccess) {
// Allow customer to proceed!
} else {
// Show premium billing modal or redirect
console.log(access.reason) // e.g. "INACTIVE_SUBSCRIPTION"
}#### 2. Activate a Subscription Plan
typescript
const result = await settle.subscriptions.activate('user_998877', 'plan_growth_monthly')
console.log(result.status) // "active" | "trialing"#### 3. Cancel an Active Subscription
typescript
const result = await settle.subscriptions.cancel('user_998877')
console.log(result.message) // "Subscription cancelled at next period end"Access Check Reasons
When checkAccess() returns hasAccess: false, one of the following audit reasons will be provided:
| Reason Code | Explanation | Resolution |
|---|---|---|
NO_ACTIVE_SUBSCRIPTION | The user has no subscription record. | Call subscriptions.activate() |
SUBSCRIPTION_EXPIRED | The cycle end date has passed. | Direct user to standard Checkout |
INSUFFICIENT_CREDITS | Debit checks failed due to zero query credits. | Trigger rewarded video ad or top-up |
FEATURE_RESTRICTED | The plan does not support this feature ID. | Prompt plan upgrade wizard |
[!TIP] Automatic Renewal Runner: Wallet-based subscriptions are audited and renewed automatically on interval by SettleSettle's background processor. You do not need to schedule periodic renewal checks.