Subscriptions
Subscriptions
Recurring billing with plans, trials, pauses, upgrades, and dunning.
Overview
Xtopay Subscriptions handles the full lifecycle of recurring revenue:
- Create plans with prices and billing intervals
- Attach customers to plans as subscriptions
- Automatically charge on each renewal date
- Retry failed payments with configurable dunning logic
- Let customers upgrade, downgrade, pause, or cancel
Subscription lifecycle
trialing → active → past_due → cancelled
↘ paused
↘ cancelled| Status | Meaning |
|---|---|
trialing | In a free trial period — no charges yet |
active | Billing normally |
past_due | Last renewal failed — in dunning retry window |
paused | Temporarily suspended at customer or merchant request |
cancelled | Ended — no further charges |
Quick start
// 1. Create a plan (usually done once in the dashboard or at startup)
const plan = await xtopay.plans.create({
name: "Pro",
amount: 5000, // GHS 50.00/month
currency: "GHS",
interval: "month",
interval_count: 1,
});
// 2. Subscribe a customer
const subscription = await xtopay.subscriptions.create({
customer_id: "cus_abc123",
plan_id: plan.id,
trial_period_days: 14,
});
// 3. Xtopay handles all renewals, retries, and webhooks from here