Subscriptions

Create subscription

Changed on Nov 3, 2026

Subscribes a customer to a plan. A new subscription is PENDING until the first charge settles: wait for subscription.active before granting access. Card subscriptions are charged automatically; bank_transfer, bank and mobile_money subscriptions are billed by invoice link each cycle.

post/v1/subscriptions

Request

Base URL
https://api.kyshi.co
Auth
API key in header x-api-key
TypeScript
https://skmtc.dev/kyshi/apis/kyshi-mor-public-api/docs/v1/subscriptions/post.ts
A function with typed inputs. Its response is checked against the schema.

Headers

idempotency-keystring required

Request body

planCodestring required

customerstring required

cardstring required

startDatestring required

paymentMethod'card' | 'mobile_money' | 'bank_transfer' | 'bank'

redirectUrlstring

invoiceLimitnumber

maxRetryCountnumber

gracePeriodDaysnumber

Example request

{
  "planCode": "plan_monthly_pro",
  "customer": "dom@yopmail.com",
  "card": "AUTH_8dfhjjdt",
  "startDate": "2026-10-01T00:00:00Z",
  "paymentMethod": "card",
  "redirectUrl": "https://merchant.example.com/subscriptions/return",
  "invoiceLimit": 12,
  "maxRetryCount": 3,
  "gracePeriodDays": 5
}

Response

Success.

statusboolean required

true on success.

messagestring required

codenumber required

Mirrors the HTTP status code.

Example response

{
  "status": true,
  "message": "Success",
  "code": 200,
  "data": {}
}

Changes

Nov 3, 20264aed77604588 Revision changes
- breaking
  the header request parameter idempotency-key became required
- breaking
  the request property became required
- breaking
  the request property became required
- breaking
  the response's body type changed from object to no type for status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- info
  the endpoint scheme security ApiKeyAuth was added to the API
- info
  the request property format was generalized from email to no format
- info
  added subschema #2 to the response body allOf list for the response status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status

Operation history