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

-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`.
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
}

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