Subscriptions

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`	Ended; can be reactivated while the paid period is still active	Revoke access, unless reactivating

A past_due subscription also pauses retries when its saved payment method can no longer be charged at all, and resumes—immediately—if a card update revives it. See Dead payment methods.

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_v2.created webhook and schedules future renewals based on the plan’s billing cycle.

Manage Subscriptions

Change Plans

Upgrade or downgrade active subscriptions:

Dashboard — Select subscription → Change Plan
SDK/API — See Change Subscription Plan

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" \
  -H "X-API-Version: 2.0.0"

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" \
  -H "X-API-Version: 2.0.0"

Immediate cancellation does not issue refunds automatically. If you want to refund, perform this action separately via API or Dashboard.

Cancellation details

Every cancelled subscription records why it ended and when, so you can tell voluntary churn apart from dunning exhaustion, workflow rules, and fraud/dispute activity. Two fields carry this — both always present on the subscription, and null until it’s cancelled:

Field	Description
`cancelled_at`	UTC timestamp of when the subscription became `cancelled`. `null` while `trial`, `active`, `past_due`, or `scheduled_for_cancellation`.
`cancellation_details`	`{ reason, trigger_payment_id }`. `reason` is server-attested; `trigger_payment_id` (prefixed `pay_`) points at the payment that caused a system cancellation, or `null` for merchant-initiated cancels.

`reason`	When it’s set	`trigger_payment_id`
`merchant_initiated`	You cancelled via API or Dashboard	`null`
`past_due_max_attempts_reached`	Dunning exhausted all retries	Last failed renewal
`workflow_action`	A workflow ended the subscription	Triggering payment
`fraud_prevention`	A fraud / pre-dispute signal cancelled it (see Fraud Prevention)	Disputed payment

For scheduled cancellations, cancellation_details is populated at schedule time (visible on the subscription_v2.scheduled_for_cancellation event) and finalized when the subscription ends. Reactivating a subscription clears both fields back to null.

The reason is server-owned — you choose the cancellation type (cancel_immediately or schedule_cancellation), never the reason. Your API and Dashboard cancels are always attributed merchant_initiated. A cancel request that includes a reason-like field (reason, cancellation_details, trigger_payment_id) is rejected with 400.

Reactivate

Set status: active with PATCH /subscriptions to reactivate a scheduled_for_cancellation or cancelled subscription. What happens depends on whether the paid period (current_period_end) is still active.

curl -X PATCH https://api.paynext.com/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 2.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription": {
      "id": "sub_a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "status": "active"
    }
  }'

Subscription	Paid period	Result
`scheduled_for_cancellation`	Still active	→ `active`, no charge
`cancelled`	Still active (`current_period_end` in the future)	→ `active`, no charge—access restored for the remaining paid period
`cancelled`	Ended (`current_period_end` in the past or unset)	PayNext attempts an immediate charge on the saved payment method

When the paid period has ended, the reactivation charge determines the outcome:

Charge succeeds → active with a new billing period.
Charge fails → past_due; the subscription enters the standard dunning flow and access is not restored.

Either way, PayNext emits a single subscription_v2 event reflecting the resulting status (subscription_v2.activated on reactivation, or subscription_v2.past_due if the reactivation charge fails).

A past_due subscription cannot be reactivated with this endpoint—collect payment via SDK checkout instead. 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_v2.past_due webhook, which carries an incremented attempt_count on each retry:

{
  "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

An attempt can also run ahead of its scheduled slot. For a payment declined for insufficient funds, the card network signals when the funds are likely there and the attempt runs at that moment instead—it replaces the scheduled attempt rather than adding one. See Funds-Available Retries.

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_v2.created`	New subscription created
`subscription_v2.activated`	Became active from a non-active state (trial → paid, or reactivation)
`subscription_v2.renewed`	Recurring renewal or past-due recovery
`subscription_v2.past_due`	A renewal failed and dunning began (one per retry)
`subscription_v2.scheduled_for_cancellation`	Cancellation scheduled for period end
`subscription_v2.cancelled`	Subscription ended (recovery exhausted or cancelled)
`subscription_v2.updated`	Plan or metadata change, or un-cancel

See Webhook Events for the full list and payload schemas.

Introduction

Use Cases

Platform

Payments

Fraud Prevention

Advanced Features

Developers

The Subscription Lifecycle

Subscription Statuses

Create a Subscription

Manage Subscriptions

Change Plans

Cancel

Schedule cancellation (recommended)

Cancel immediately

Cancellation details

Reactivate

Handle Failed Payments

Automatic retry

Billing date on recovery

Recovery exhausted

Webhook Events

​The Subscription Lifecycle

​Subscription Statuses

​Create a Subscription

​Manage Subscriptions

​Change Plans

​Cancel

​Schedule cancellation (recommended)

​Cancel immediately

​Cancellation details

​Reactivate

​Handle Failed Payments

​Automatic retry

​Billing date on recovery

​Recovery exhausted

​Webhook Events

The Subscription Lifecycle

Subscription Statuses

Create a Subscription

Manage Subscriptions

Change Plans

Cancel

Schedule cancellation (recommended)

Cancel immediately

Cancellation details

Reactivate

Handle Failed Payments

Automatic retry

Billing date on recovery

Recovery exhausted

Webhook Events