Subscription Reads

Overview

The Subscription Reads endpoints let you inspect everything about a subscription without changing it. Use them to:

Display subscription status and next charge date to customers in your dashboard
Pull charge history for receipts, reconciliation, or support queries
Preview upcoming billing dates to send payment reminders
Audit every action ever taken on a subscription via the event log

All read endpoints use the subscription id (integer) — not the planCode or enrollmentReference. Make sure you have saved data.subscription.id from when the subscription was created.

Key Requirements

Retrieve your API keys from your dashboard by following the steps on our Authentication page. Use your public API key for all read requests.

Set the following headers on every request:

{
  "Authorization": "Payaza <Public API Key encoded in base 64>"
}

Get Subscription

Retrieves the full details of a single subscription by its id. Use this to check status, next charge date, trial end date, or any other field on the subscription record.

curl --request GET \
  --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20 \
  --header 'Authorization: Payaza <Public API Key encoded in base 64>' \

Path parameter

Parameter	Type	Description
`id`	Integer	The subscription ID from the Create Subscription response

Sample response

{
  "success": true,
  "message": "Success",
  "data": {
    "id": 20,
    "customerId": "CUST-12345",
    "customerEmail": "johndoe@example.com",
    "firstName": null,
    "lastName": null,
    "status": "ACTIVE",
    "currentPeriodStart": "2026-07-08T19:35:52.348327",
    "currentPeriodEnd": "2026-08-08T19:35:55.569925",
    "nextChargeDate": "2026-08-08T19:35:55.569925",
    "trialEndDate": null,
    "pauseResumesAt": null,
    "cancelAt": null,
    "pausedAt": null,
    "cancelledAt": null,
    "cancellationReason": null,
    "cardExpiryAlertSent": false,
    "connectionMode": "Live",
    "enrollmentReference": "SUBREF_BFE417ABF6FF49A985",
    "enrollmentTxnReference": "SUB_ENROLL_20_1783539352354",
    "chargeMode": "DIRECT_CHARGE",
    "metadata": null,
    "createdAt": "2026-07-08T19:35:52.34833",
    "updatedAt": "2026-07-08T19:35:55.573662",
    "customerBearsFee": false,
    "enrollConfirmed": true
  }
}

Key fields explained

Field	What it tells you
`status`	Current subscription state — see status table in Create a Subscription
`nextChargeDate`	When the next automatic charge will be attempted
`currentPeriodStart` / `currentPeriodEnd`	The start and end of the current billing window
`trialEndDate`	When the free trial ends (null if no trial)
`pauseResumesAt`	When a paused subscription will automatically resume (null if not paused or no auto-resume set)
`cancelledAt`	Timestamp of cancellation (null if not cancelled)
`enrollConfirmed`	Whether the card enrolment was fully confirmed with the card network

API reference: Get Subscription

List Subscriptions

Retrieve a paginated list of all subscriptions belonging to your account. Filter by status to find active, paused, cancelled, or past-due subscriptions.

curl --request GET \
  --url 'https://api.payaza.africa/live/subscription/api/v1/subscriptions?page=0&size=10&status=ACTIVE' \
  --header 'Authorization: Payaza <Public API Key encoded in base 64>' \

Query parameters

Parameter	Required	Description
`page`	✓	Page number — starts at `0`
`size`	✓	Number of records per page
`status`	✓	Filter by subscription status: `ACTIVE`, `PAUSED`, `CANCELLED`, `TRIALING`, `PAST_DUE`, or `INCOMPLETE`

Sample response

{
  "success": true,
  "message": "Success",
  "data": {
    "content": [
      {
        "subscription": {
          "id": 20,
          "customerId": "CUST-12345",
          "customerEmail": "johndoe@example.com",
          "status": "ACTIVE",
          "nextChargeDate": "2026-08-08T19:35:55.569925",
          "currentPeriodStart": "2026-07-08T19:35:52.348327",
          "currentPeriodEnd": "2026-08-08T19:35:55.569925",
          "enrollmentReference": "SUBREF_BFE417ABF6FF49A985",
          "chargeMode": "DIRECT_CHARGE",
          "createdAt": "2026-07-08T19:35:52.34833"
        },
        "plan": {
          "id": 69,
          "name": "Pro Monthly",
          "description": "Full access billed monthly",
          "amount": 5000,
          "currency": "NGN",
          "interval": "MONTHLY",
          "planCode": "PLN_821DCFD",
          "status": "ACTIVE"
        }
      }
    ],
    "totalElements": 1,
    "totalPages": 1,
    "first": true,
    "last": true
  }
}

Each item in content contains both a subscription object and a plan object — giving you the customer’s billing state and the plan details in a single response without a second API call.

API reference: List Subscriptions

Upcoming Charges

Returns a list of the next scheduled charge dates and amounts for a subscription. Use this to show customers what they will be billed and when, or to send payment reminders ahead of the next cycle.

curl --request GET \
  --url 'https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/upcoming?count=5' \
  --header 'Authorization: Payaza <YOUR_PUBLIC_KEY>' \

Query parameters

Parameter	Required	Description
`count`	✓	Number of upcoming charges to return. Defaults to `5`

Sample response

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "chargeDate": "2026-08-08T19:35:55.569925",
      "amount": 5000,
      "currency": "NGN"
    },
    {
      "chargeDate": "2026-09-08T19:35:55.569925",
      "amount": 5000,
      "currency": "NGN"
    },
    {
      "chargeDate": "2026-10-08T19:35:55.569925",
      "amount": 5000,
      "currency": "NGN"
    },
    {
      "chargeDate": "2026-11-08T19:35:55.569925",
      "amount": 5000,
      "currency": "NGN"
    },
    {
      "chargeDate": "2026-12-08T19:35:55.569925",
      "amount": 5000,
      "currency": "NGN"
    }
  ]
}

API reference: Upcoming Charges

Subscription Charge History

Returns a paginated list of all past billing attempts for a subscription — both successful and failed. Use this for payment receipts, support queries, or reconciliation.

curl --request GET \
  --url 'https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/charges?page=0&size=10' \
  --header 'Authorization: Payaza <Public API Key encoded in base 64>' \

Query parameters

Parameter	Required	Description
`page`	✓	Page number — starts at `0`
`size`	✓	Number of records per page

Sample response

{
  "success": true,
  "message": "Success",
  "data": {
    "content": [
      {
        "id": 3,
        "subscriptionId": 20,
        "cycleNumber": 1,
        "attemptNumber": 1,
        "transactionReference": "SUB_ENROLL_20_1783539352354",
        "amount": 5000,
        "currency": "NGN",
        "description": "Subscription cycle 1 (enrollment charge)",
        "status": "SUCCESS",
        "failureReason": null,
        "isRetriable": null,
        "chargedAt": "2026-07-08T19:38:18.307260",
        "nextRetryAt": null,
        "createdAt": "2026-07-08T19:38:18.307196"
      },
      {
        "id": 9,
        "subscriptionId": 20,
        "cycleNumber": 2,
        "attemptNumber": 1,
        "transactionReference": "SUB_CYCLE_2_A11783542029433",
        "amount": 5000,
        "currency": "NGN",
        "description": "Subscription cycle 2",
        "status": "SUCCESS",
        "failureReason": null,
        "isRetriable": null,
        "chargedAt": "2026-08-08T20:20:29.433374",
        "nextRetryAt": null,
        "createdAt": "2026-08-08T20:20:29.433369"
      }
    ],
    "totalElements": 2,
    "totalPages": 1,
    "first": true,
    "last": true
  }
}

Key fields explained

Field	What it tells you
`cycleNumber`	Which billing cycle this charge belongs to (1 = enrollment/first charge)
`attemptNumber`	Retry count for this cycle — `1` means first attempt, `2` means one retry, etc.
`status`	`SUCCESS` or `FAILED`
`failureReason`	Plain-text reason if the charge failed (e.g. insufficient funds, expired card)
`isRetriable`	Whether Payaza will automatically retry a failed charge
`nextRetryAt`	When the next automatic retry is scheduled (null if resolved or not retrying)

API reference: Subscription Charge History

Subscription Event History

Returns a paginated audit trail of every significant action that has occurred on a subscription. This includes creation, successful charges, payment failures, pauses, resumes, cancellations, plan changes, and status transitions. Use this for support queries (“what happened to this subscription?”), compliance auditing, or debugging unexpected state changes.

curl --request GET \
  --url 'https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/events?page=0&size=20' \
  --header 'Authorization: Payaza <Public API Key encoded in base 64>' \

Query parameters

Parameter	Required	Description
`page`	✓	Page number — starts at `0`
`size`	✓	Number of records per page

Sample response

{
  "success": true,
  "message": "Success",
  "data": {
    "content": [
      {
        "id": 3,
        "subscriptionId": 20,
        "cycleNumber": 1,
        "attemptNumber": 1,
        "transactionReference": "SUB_ENROLL_20_1783539352354",
        "amount": 5000,
        "currency": "NGN",
        "description": "Subscription cycle 1 (enrollment charge)",
        "status": "SUCCESS",
        "failureReason": null,
        "isRetriable": null,
        "isExternal": false,
        "chargedAt": "2026-07-08T19:38:18.307260",
        "nextRetryAt": null,
        "createdAt": "2026-07-08T19:38:18.307196"
      },
      {
        "id": 9,
        "subscriptionId": 20,
        "cycleNumber": 2,
        "attemptNumber": 1,
        "transactionReference": "SUB_CYCLE_2_A11783542029433",
        "amount": 5000,
        "currency": "NGN",
        "description": "Subscription cycle 2",
        "status": "SUCCESS",
        "failureReason": null,
        "isRetriable": null,
        "isExternal": false,
        "chargedAt": "2026-08-08T20:20:29.433374",
        "nextRetryAt": null,
        "createdAt": "2026-08-08T20:20:29.433369"
      }
    ],
    "totalElements": 2,
    "totalPages": 1,
    "first": true,
    "last": true
  }
}

Difference between Charge History and Event History

	Charge History	Event History
Covers	Payment attempts only (charges and retries)	All subscription actions (charges, pauses, cancellations, plan changes, status transitions)
Use for	Receipts, reconciliation, payment support	Full audit trail, debugging, compliance
Endpoint	`/subscriptions/{id}/charges`	`/subscriptions/{id}/events`

API reference: Subscription Event History

Developer notes

The id used in all read endpoints is the integer id from the Create Subscription response — not the enrollmentReference (which starts with SUBREF_) or the planCode.
Use Get Subscription for real-time status checks (e.g. before granting access to a feature). Use List Subscriptions for bulk operations or building admin dashboards.
Use Upcoming Charges to power payment reminder emails — fetch the next 1–3 dates and send a notification a few days before each one.
Use Charge History for generating customer receipts and reconciling your accounts. Each entry has a transactionReference you can use to trace the charge in your payment records.
Use Event History for support and debugging. It is the most complete picture of what happened to a subscription and when.
Results from all paginated endpoints start at page: 0, not page: 1. Passing page=1 returns the second page, not the first.

Get Started

Developer Tools

Accept Payments

Send Money

Disputes & Refunds

Account Management

Subscriptions

Split Settlements

Overview

Key Requirements

Get Subscription

List Subscriptions

Upcoming Charges

Subscription Charge History

Subscription Event History

Developer notes

​Overview

​Key Requirements

​Get Subscription

​List Subscriptions

​Upcoming Charges

​Subscription Charge History

​Subscription Event History

​Developer notes

Overview

Key Requirements

Get Subscription

List Subscriptions

Upcoming Charges

Subscription Charge History

Subscription Event History

Developer notes