Subscriptions automate recurring billing by linking customers to plans. Define billing cycles, trial periods, and pricing once—PayNext handles charges, renewals, and failed payment recovery automatically.
Before creating subscriptions, set up a recurring plan in your Dashboard. See Plans to learn how to configure billing cycles, trial periods, and pricing. The Subscription Lifecycle
When a customer completes checkout with a recurring plan, PayNext creates a subscription and manages it through these stages:
Subscription Statuses
| Status | Description | Your Action |
|---|
trial | In trial period, no charge yet | Provision access |
active | Billing successful, good standing | Maintain access |
past_due | Renewal failed, retrying for 30 days | Keep access, notify customer |
scheduled_for_cancellation | Cancellation queued for cycle end | Maintain access until cycle ends |
cancelled | Permanently ended (terminal) | Revoke access |
Create a Subscription
Include a recurring plan.id in your client session. When checkout completes, PayNext creates the subscription automatically.
{
"customer": {
"email": "[email protected]",
"address": { "country": "US" }
},
"plan": {
"id": "plan_7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}
}
subscription.created webhook and schedules future renewals based on the plan’s billing cycle.
Manage Subscriptions
Change Plans
Upgrade or downgrade active subscriptions:
Editing a plan in the Dashboard only affects new subscriptions. Existing subscribers keep their original terms.
Cancel
You can cancel subscriptions immediately or schedule cancellation for the end of the billing cycle.
Schedule cancellation (recommended)
Customer keeps access until the current billing cycle ends, then transitions to cancelled.
- Dashboard — Select subscription → Cancel → At end of billing cycle
- API —
POST /subscriptions/schedule-cancel/{id}
curl -X POST https://api.paynext.com/subscriptions/schedule-cancel/sub_a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
-H "Authorization: Bearer YOUR_API_KEY"
scheduled_for_cancellation and automatically transitions to cancelled when the cycle ends.
Ends the subscription now. Customer loses access immediately.
- Dashboard — Select subscription → Cancel → Immediately
- API —
POST /subscriptions/cancel/{id}
curl -X POST https://api.paynext.com/subscriptions/cancel/sub_a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
-H "Authorization: Bearer YOUR_API_KEY"
Immediate cancellation does not issue refunds automatically. If you want to refund, perform this action separately via API or Dashboard.
Reactivate
If a customer changes their mind before the billing cycle ends (scheduled_for_cancellation):
curl -X PATCH https://api.paynext.com/subscriptions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subscription": {
"id": "sub_a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"status": "active"
}
}'
Handle Failed Payments
When a renewal payment fails, PayNext automatically retries up to 8 times. During this period, the subscription remains past_due.
Notify users when their payment fails and prompt them to update their payment method. Use the SDK to let customers recover their subscription directly. See Recover Subscriptions. Automatic retry
PayNext attempts recovery automatically. Track progress via the subscription.updated webhook:
{
"past_due": {
"attempt_count": 3,
"max_attempts_count": 8
}
}
| Field | Description |
|---|
attempt_count | Number of recovery attempts made so far |
max_attempts_count | Maximum attempts before subscription cancels |
Billing date on recovery
When recovery succeeds, the next billing date shifts to the recovery date plus one billing interval—not from the original renewal date.
Example: A 28-day subscription was due to renew on Dec 1, but the payment failed. Recovery succeeds on Dec 5. The next billing date is Jan 2 (Dec 5 + 28 days), not Dec 29 (Dec 1 + 28 days).
Recovery exhausted
If all 8 retry attempts fail, the subscription automatically transitions to cancelled.
Webhook Events
Listen for these events to keep your system in sync:
| Event | When it fires |
|---|
subscription.created | New subscription created |
subscription.updated | Status changed, plan changed, or recovery attempt made |
subscription.cancelled | Subscription ended (recovery exhausted or cancelled) |
