Subscriptions connect a customer to a plan and manage recurring payment attempts over time.

Recommended Flow

1. Create a plan.
2. Create a subscription with the plan code and customer email.
3. If checkout or card authorization is required, redirect the customer to the returned payment URL.
4. Monitor subscription webhooks and payment attempts.
5. Use retry endpoints for failed or past-due payments.
6. Cancel, reactivate, or mark subscriptions as non-renewing when needed.

Status Lifecycle

Subscriptions can be PENDING, ACTIVE, PAST_DUE, NON_RENEWING, COMPLETED, or CANCELLED.

Retry Behavior

Use maxRetryCount and gracePeriodDays when creating a subscription to control how Kyshi handles failed recurring payments. Use the retry endpoint when you need to trigger a retry manually.

Integration Notes

• Create the plan first, then create the subscription with the plan code.
• Store the subscription code and customer email in your system.
• Listen for subscription and invoice webhooks so your customer access stays in sync.
• Use retry and manage endpoints for deliberate customer support actions.
• Reconcile invoices and payment attempts when investigating failed billing.

For exact request and response schemas, see Reference > Subscriptions.