SettleSettle | Developer Hub

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 renewal

Method 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.