> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Reads

> Fetch subscription details, charge history, upcoming billing dates, and the full event audit trail.

## 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

<Note>
  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.
</Note>

***

## Key Requirements

<Info>
  Retrieve your API keys from your dashboard by following the steps on our [Authentication](/guides/authentication) page. Use your **public API key** for all read requests.
</Info>

Set the following headers on every request:

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20 \
    --header 'Authorization: Payaza <Public API Key encoded in base 64>' \
  ```
</CodeGroup>

**Path parameter**

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

**Sample response**

```json theme={null}
{
  "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](/guides/subscriptions) |
| `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](/api-reference/subscription-reads/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.

<CodeGroup>
  ```bash cURL — All active subscriptions theme={null}
  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>' \
  ```
</CodeGroup>

**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**

```json theme={null}
{
  "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
  }
}
```

<Note>
  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.
</Note>

**API reference:** [List Subscriptions](/api-reference/subscription-reads/list-subscription)

***

## 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.

<CodeGroup>
  ```bash cURL — Next 5 charges (default) theme={null}
  curl --request GET \
    --url 'https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/upcoming?count=5' \
    --header 'Authorization: Payaza <YOUR_PUBLIC_KEY>' \
  ```
</CodeGroup>

**Query parameters**

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

**Sample response**

```json theme={null}
{
  "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](/api-reference/subscription-reads/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.

<CodeGroup>
  ```bash cURL theme={null}
  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>' \
  ```
</CodeGroup>

**Query parameters**

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

**Sample response**

```json theme={null}
{
  "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](/api-reference/subscription-reads/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.

<CodeGroup>
  ```bash cURL theme={null}
  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>' \
  ```
</CodeGroup>

**Query parameters**

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

**Sample response**

```json theme={null}
{
  "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](/api-reference/subscription-reads/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.