You do this by making a GET request to subscriptions endpoint from your server.

-H "x-api-key: your_secret_key".

GET {{host}}/v1/subscriptions/:subscriptionIdOrCode

Path Parameters

Field	Data type	Description
subscriptionIdOrCode	string.	The subscription ID or code you want to fetch.

If the API call is successful, Kyshi returns the following response:

{
  "status": true,
  "message": "Success",
  "code": 200,
  "data": {
    "id": "7697cabd-ee1b-435a-9ae3-82b926cc5334",
    "code": "SUB_7263269_W-dnE2xtS015ETu",
    "status": "ACTIVE",
    "isActive": true,
    "startDate": "2026-05-01T00:00:00.000Z",
    "previousPaymentDate": "2026-05-01T00:00:00.000Z",
    "nextPaymentDate": "2026-06-01T00:00:00.000Z",
    "currentPeriodStart": "2026-05-01T00:00:00.000Z",
    "currentPeriodEnd": "2026-06-01T00:00:00.000Z",
    "pastDueAt": null,
    "nextRetryAt": null,
    "retryCount": 0,
    "maxRetryCount": 3,
    "gracePeriodDays": 3,
    "cancelledAt": null,
    "cancelReason": null,
    "invoiceLimit": 12,
    "invoicesPaid": 1,
    "mode": "live",
    "createdAt": "2026-05-01T00:00:00.000Z",
    "updatedAt": "2026-05-01T00:00:00.000Z",
    "plan": {
      "id": "4a3fc25a-6056-4daa-b9bb-9380904d5751",
      "name": "Premium Plan",
      "description": "Monthly premium access",
      "interval": "monthly",
      "amount": 5000,
      "settlementAmount": null,
      "settlementCurrency": null,
      "code": "PLN_xxxxxxxxxxxxx",
      "sendSms": false,
      "sendInvoices": false,
      "hostedPage": false,
      "isActive": true
    },
    "customer": {
      "id": "e48419c7-701d-4933-93c7-2e8eeaf09bce",
      "firstName": null,
      "lastName": null,
      "phoneNumber": null,
      "email": "[email protected]",
      "customerCode": null,
      "currencyCode": "NGN",
      "active": true
    },
    "card": {
      "id": "bdc39678-ef30-4cd1-ab88-14ff979f9132",
      "bin": "408408",
      "last4": "0409",
      "expMonth": "01",
      "expYear": "2030",
      "cardType": "visa",
      "bank": "TEST BANK",
      "countryCode": "NG",
      "brand": "visa",
      "reusable": true,
      "authorizationCode": "AUTH_b7ymikof8e",
      "active": true,
      "currencyCode": "NGN"
    }
  }
}

Response Fields

Field	Description
status	Current subscription status. One of ACTIVE, PAST_DUE, NON_RENEWING, COMPLETED, CANCELLED.
isActive	Entitlement flag. If true, the customer should have access.
startDate	Date the subscription starts.
previousPaymentDate	Last successful billing date.
nextPaymentDate	Next scheduled billing date or retry date.
currentPeriodStart	Start of the current paid billing period.
currentPeriodEnd	End of the current paid billing period.
pastDueAt	Date the subscription first became past due.
nextRetryAt	Next retry date for failed renewal payments.
retryCount	Number of retry attempts made in the current failed billing cycle.
maxRetryCount	Maximum retry attempts allowed.
gracePeriodDays	Number of days before a failed subscription is cancelled.
cancelledAt	Date the subscription was cancelled.
cancelReason	Reason for cancellation, if available.
invoiceLimit	Maximum number of successful billing cycles. `null` means billing continues until cancelled.
invoicesPaid	Number of successful billing cycles completed.
mode	`test` or `live`.

Access Control

Use both status and isActive to determine access.

Grant Access When

status = ACTIVE and isActive = true

Do NOT Grant Access When

status = PAST_DUE
status = CANCELLED
status = COMPLETED
isActive = false

NON_RENEWING Behavior

status = NON_RENEWING and isActive = true → access allowed until currentPeriodEnd

Error Responses

HTTP Status	Error Code	Description
404	NOT_FOUND	Subscription not found.
401	UNAUTHORIZED	Invalid or missing API key.
422	UNPROCESSABLE_ENTITY	Invalid subscription ID or code.