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

Kyshi subscriptions support both card auto-collection and invoice-based collection for non-card payment methods such as bank transfer, bank, and mobile money.

Recommended Flow

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

Collection Modes

Payment Method	Behavior
`card`	Kyshi can charge the saved card or card authorization for recurring billing and retry failed payments.
`bank_transfer`	Kyshi generates subscription invoices and payment links or payment instructions. The customer completes payment manually by bank transfer.
`bank`	Kyshi generates subscription invoices and payment links or payment instructions for bank-based payment.
`mobile_money`	Kyshi generates subscription invoices and payment links or payment instructions for mobile money payment.

For non-card subscription methods, "manual" means the customer completes payment through the generated payment link or channel. Kyshi tracks invoices, payment attempts, reminders, status changes, and webhooks. It does not mean the merchant can mark an offline payment as paid unless a separate reconciliation or mark-paid endpoint is provided for that workflow.

Reminders And Invoices

Use plans with sendInvoices: true when customers should receive subscription invoice and payment reminders. Reminder behavior depends on your business notification configuration and the subscription billing worker being enabled in the target environment.

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.