---
title: Subscriptions
description: Charge a customer the same amount on a schedule, after they agree once.
---

:::note[In a nutshell]
A subscription asks a customer to agree once to be charged a fixed amount every day, week or month. After that, each charge is taken with no prompt and no action from them. They approve on their own network, or with their PIN in the iSmartPay app for a wallet. You pause, resume or cancel from the API or the console.
:::

A gym, a newsletter or a loan repayment is the usual case. You create the subscription when the customer signs up. We take the money on each due date.

## Why use subscriptions

- **Ask once, charge every time.** The customer agrees one time. After that, each charge needs nothing from them: no prompt to answer, and no reminder for you to send on the 1st.
- **Their phone, their network.** MTN and Telecel customers approve on their own network. Wallet customers approve with their PIN in the iSmartPay app.
- **Failed charges try again.** A charge that fails for a reason that can fix itself, like a low balance, is tried again after 1, 3 and 7 days. You choose how many tries, and what happens if every one fails.
- **Paid like any other collection.** A paid charge is your money. It shows in your wallet and settles on your usual schedule.
- **Test months in minutes.** The sandbox clock runs the next charge on demand, so you can watch a whole year of billing before you go live.

Your business has to be switched on for subscriptions. Until it is, creating one answers `503 provider_unavailable`. Start in the sandbox. Keys need the `mandates.write` permission to change subscriptions and `mandates.read` to read them.

## Create a subscription

```http
POST /v1/subscriptions
Idempotency-Key: gym-ama-2026-12
```

```json
{
  "reference": "gym-ama-2026-12",
  "priceData": { "amount": "150.00", "currency": "GHS", "interval": "month" },
  "customer": { "phone": "0244123456", "network": "mtn" },
  "paymentMethod": "mobile_money",
  "startDate": "2026-12-01",
  "billingTime": "09:00",
  "maxCycles": 12,
  "retry": { "afterDays": [1, 3, 7] },
  "pastDueBehavior": "cancel",
  "description": "Gym membership"
}
```

- `reference` is yours, and unique for each subscription. Send the same reference and body again after a timeout and you get the same subscription back. A different body with the same reference is `409 idempotency_key_reused`.
- `priceData.interval` is `day`, `week` or `month`. A weekly subscription charges on the weekday of `startDate`. A monthly one charges on that day of the month, and on the last day of shorter months.
- `paymentMethod` is `mobile_money` or `wallet`. For mobile money, `customer.network` is `mtn` or `telecel`. For a wallet, leave it out; `customer.phone` is the number verified on the customer's iSmartPay account, and wallets charge in GHS only.
- `startDate` is the day of the first charge. It must be in the future.
- `endDate` and `maxCycles` both stop the subscription. Use either or both.
- `retry.afterDays` is `[1, 3, 7]` by default. You can send a shorter list that starts the same way (`[1]`, `[1, 3]`) or `[]` for no retries. Other days are not offered yet.
- `pastDueBehavior` is what happens when every retry of a cycle has failed: `cancel` (the default), `pause` or `keep_charging`.
- `description` is shown to the customer when they approve, up to 60 characters.

The customer pays the fee on every charge. It is fixed when you create the subscription and never changes, so `fee` and `totalAmount` in the answer are what they pay each time.

The answer is `202`:

```json
{
  "id": "sub_0f1d6a3c7b114a549a3b6f1c2f0e8f6e",
  "reference": "gym-ama-2026-12",
  "status": "incomplete",
  "customer": { "phone": "0244123456", "network": "mtn" },
  "paymentMethod": "mobile_money",
  "priceData": { "amount": "150.00", "currency": "GHS", "interval": "month", "intervalCount": 1 },
  "fee": "2.25",
  "totalAmount": "152.25",
  "consent": { "channel": "network", "expiresAt": "2026-11-23T09:00:00Z" },
  "nextChargeAt": "2026-12-01T09:00:00Z",
  "cyclesCharged": 0,
  "cancelAtPeriodEnd": false
}
```

The values above only show the shape. The answer is the same whether or not the customer's number has an iSmartPay account, so it never tells you.

## How the customer agrees

| Payment method | The customer |
| -------------- | ------------ |
| MTN | Gets MTN's own approval prompt with your business name, the amount and how often, and approves with their MoMo PIN. |
| Telecel | Pays the first charge as a normal Telecel prompt on `startDate`. Paying it is the agreement. |
| Wallet | Approves in the iSmartPay app with their PIN. |

A subscription nobody answers becomes `incomplete_expired` after 7 days. The customer can also decline. `declineReason` says which.

## Statuses

| `status` | Meaning |
| -------- | ------- |
| `incomplete` | Waiting for the customer. |
| `incomplete_expired` | They declined or never answered. See `declineReason`. |
| `trialing` | Approved, and the first charge is still to come. |
| `active` | Charging on schedule. |
| `past_due` | Every retry of a cycle failed. `pastDueBehavior` says what happens next. |
| `unpaid` | Past due, with `pastDueBehavior` set to `keep_charging`. Only the GET shows `unpaid`; the webhook says `past_due`. |
| `paused` | No charges. `pausedBy` is `platform` when iSmartPay stopped them. Contact support. |
| `canceled` | Ended. `cancelReason` is `business`, `network` (the customer canceled with their network) or `platform`. |
| `completed` | Reached `endDate` or `maxCycles`. |

## Read, pause, resume and cancel

```http
GET /v1/subscriptions?status=active&limit=50
GET /v1/subscriptions/{id}
GET /v1/subscriptions/{id}/charges
POST /v1/subscriptions/{id}/pause
POST /v1/subscriptions/{id}/resume
POST /v1/subscriptions/{id}/cancel
```

Pause, resume and cancel need an `Idempotency-Key`. Pausing stops charging and leaves the customer's agreement in place, so resuming needs nothing from them. Cancel ends it now. Send `{"atPeriodEnd": true}` to let it stay until the next cycle that is not already being charged, then end. It shows `cancelAtPeriodEnd` and `cancelAt` until then. A subscription that cannot make the change, such as pausing a canceled one, is `409 mandate_not_open`.

`GET .../charges` lists every attempt with its cycle, `status` and, for a failed one, `failureReason` and `nextAttemptAt`. A charge is `paid`, `failed` (it will be tried again), `uncollectible` (no more tries this cycle), `void` or `missed`. A cycle that fell more than a day behind is skipped and shown as `missed`. We never charge twice to catch up.

## Webhooks

| Event | When |
| ----- | ---- |
| `subscription.created` | A subscription was created and the customer has been asked. |
| `subscription.status_changed` | The status changed, or you set a cancel for the period end. It carries `previousStatus`. |
| `subscription.charge_upcoming` | A charge is due within three days. |
| `subscription.charge_succeeded` | A charge was paid. |
| `subscription.charge_failed` | An attempt failed. `nextAttemptAt` is `null` when the cycle has no more attempts. |

Keys need `mandates.read` to see them in `GET /v1/events`. An existing endpoint starts receiving them after you edit it once in the console. See [Webhooks](/guides/webhooks).

## Test in the sandbox

`POST /v1/test-helpers/subscriptions/{id}/advance` with `{"to": "next_charge"}` runs the next reminder, charge or retry now, as if the time had come. Send a timestamp instead to run everything due by then. The sandbox outcome numbers decide whether the charge succeeds. On the live API this answers `404`.

## The console

The console lists your subscriptions, shows each one's charges, and lets owners and admins pause, resume and cancel. It cannot create one; that is done with the API.
