Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.paynext.com/llms.txt

Use this file to discover all available pages before exploring further.

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

StatusDescriptionYour Action
trialIn trial period, no charge yetProvision access
activeBilling successful, good standingMaintain access
past_dueRenewal failed, retrying for 30 daysKeep access, notify customer
scheduled_for_cancellationCancellation queued for cycle endMaintain access until cycle ends
cancelledPermanently 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": "customer@example.com",
    "address": { "country": "US" }
  },
  "plan": {
    "id": "plan_7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
  }
}
PayNext sends a 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. 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"
The subscription moves to scheduled_for_cancellation and automatically transitions to cancelled when the cycle ends.

​
Cancel immediately

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"
    }
  }'
For past_due or cancelled subscriptions, you must collect payment first. See Recover Subscriptions.

​
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
  }
}
FieldDescription
attempt_countNumber of recovery attempts made so far
max_attempts_countMaximum 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:
EventWhen it fires
subscription.createdNew subscription created
subscription.updatedStatus changed, plan changed, or recovery attempt made
subscription.cancelledSubscription ended (recovery exhausted or cancelled)
See Webhook Events for the full list and payload schemas.