Create a subscription for a customer using an existing plan code.

Use paymentMethod to choose the collection mode. card is for card auto-collection. bank_transfer, bank, and mobile_money are invoice-based collection methods where Kyshi creates invoices and payment links or instructions for the customer to complete payment.

For invoice-based subscription reminders, create the plan with sendInvoices: true and confirm that your business notification settings are configured.

-H "x-api-key: your_secret_key"
-H "idempotency-key: unique-request-key"

POST {{host}}/v1/subscriptions

Request Body

Field	Data Type	Required	Description
planCode	string	Yes	Plan code, for example `PLN_abc123`.
customer	string	Yes	Customer email address.
card	string	No	Saved card/authorization identifier for card subscriptions.
startDate	string	No	ISO date/time to start the subscription.
paymentMethod	string	No	`card`, `mobile_money`, `bank_transfer`, or `bank`. Use `card` for auto-collection and non-card methods for invoice/payment-link collection.
redirectUrl	string	No	Redirect URL for hosted payment steps.
invoiceLimit	number	No	Maximum number of invoices to generate before completing the subscription.
maxRetryCount	number	No	Maximum retry attempts for failed invoices.
gracePeriodDays	number	No	Grace period before cancellation after failed retries.

{
  "planCode": "PLN_abc123",
  "customer": "[email protected]",
  "paymentMethod": "card",
  "redirectUrl": "https://merchant.example.com/subscriptions/callback",
  "invoiceLimit": 12,
  "maxRetryCount": 3,
  "gracePeriodDays": 3
}

{
  "planCode": "PLN_abc123",
  "customer": "[email protected]",
  "paymentMethod": "bank_transfer",
  "redirectUrl": "https://merchant.example.com/subscriptions/callback",
  "invoiceLimit": 12,
  "maxRetryCount": 3,
  "gracePeriodDays": 3
}

{
  "status": true,
  "message": "Success",
  "code": 201,
  "data": {
    "id": "93ad2450-b49f-4c3f-a871-52a5455bdf62",
    "code": "SUB_abc123",
    "status": "ACTIVE",
    "paymentMethod": "card",
    "startDate": "2026-05-20T10:15:00.000Z",
    "nextPaymentDate": "2026-06-20T10:15:00.000Z",
    "retryCount": 0,
    "maxRetryCount": 3,
    "gracePeriodDays": 3
  }
}