Subscription Lifecycle

Overview

Once a subscription is created and ACTIVE, you have full control over how it behaves over time. This page covers the four operations that change a subscription’s state:

Operation	What it does	Reversible?
Pause	Temporarily suspends billing	✓ Yes — resume manually or at a set date
Resume	Lifts a pause and restarts billing	✓ Yes
Cancel	Permanently stops all billing	✗ No — terminal action
Change Plan	Moves the customer to a different pricing plan	✓ Yes — can change again

All lifecycle operations use the subscription id (integer) from the Create Subscription response — not the planCode. Make sure you have saved data.subscription.id before calling any of these endpoints.

Key Requirements

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

Set the following headers on every request:

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

Pause a Subscription

Suspends recurring billing for a subscription. No charges will be attempted while the subscription is PAUSED. The customer’s card remains enrolled — billing resumes when the pause is lifted. You can set an optional resumeAt date to automatically restart billing on a specific date. If you omit it, the subscription stays paused until you manually call Resume.

curl --request PATCH \
  --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/pause \
  --header 'Authorization: Payaza <Public API Key encoded in base 64>' \
  --header 'Content-Type: application/json' \
  --data '{
    "resumeAt": "2026-08-01T00:00:00"
  }'

curl --request PATCH \
  --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/pause \
  --header 'Authorization: Payaza Payaza <Public API Key encoded in base 64>' \
  --header 'Content-Type: application/json' \
  --data '{}'

Path parameter

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

Body parameters

Parameter	Type	Required	Description
`resumeAt`	String (ISO 8601)	No	Date and time to automatically resume billing (e.g. `"2026-08-01T00:00:00"`). Omit to pause indefinitely

Sample response

{
  "success": true,
  "message": "Subscription paused",
  "data": {
    "id": 20,
    "customerEmail": "johndoe@example.com",
    "status": "PAUSED",
    "enrollmentReference": "SUBREF_BFE417ABF6FF49A985",
    "enrollmentTxnReference": "SUB_ENROLL_20_1783539352354",
    "pausedAt": "2026-07-08T22:05:03.791857158",
    "pauseResumesAt": "2026-08-01T00:00:00.000000000"
  }
}

API reference: Pause Subscription

Resume a Subscription

Lifts a pause and restarts automatic billing. The next charge date is recalculated from the moment the subscription resumes. Only subscriptions with a status of PAUSED can be resumed.

Resume has no request body — just pass the subscription id in the URL.

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

Sample response

{
  "success": true,
  "message": "Subscription resumed",
  "data": {
    "id": 20,
    "customerEmail": "johndoe@example.com",
    "status": "ACTIVE",
    "enrollmentReference": "SUBREF_BFE417ABF6FF49A985",
    "enrollmentTxnReference": "SUB_ENROLL_20_1783539352354"
  }
}

API reference: Resume Subscription

Cancel a Subscription

Permanently cancels a subscription. Once cancelled, all future billing stops immediately and nextChargeDate is cleared. This cannot be undone.

Cancellation is a terminal action. Once a subscription is CANCELLED, it cannot be reactivated. If a customer wants to re-subscribe later, you must create a brand new subscription for them.

curl --request PATCH \
  --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/cancel \
  --header 'Authorization: Payaza <Public API Key encoded in base 64>' \
  --header 'Content-Type: application/json' \
  --data '{
    "reason": "customer_request"
  }'

Path parameter

Parameter	Type	Description
`id`	Integer	The subscription ID to cancel

Body parameters

Parameter	Type	Required	Description
`reason`	String	✓	The reason for cancellation. Use a descriptive string such as `customer_request`, `payment_failed`, or `merchant_initiated`

Sample response

{
  "success": true,
  "message": "Subscription cancelled",
  "data": {
    "id": 20,
    "customerEmail": "johndoe@example.com",
    "status": "CANCELLED",
    "enrollmentReference": "SUBREF_BFE417ABF6FF49A985",
    "enrollmentTxnReference": "SUB_ENROLL_20_1783539352354",
    "cancelledAt": "2026-07-08T22:07:36.154580616",
    "cancellationReason": "customer_request"
  }
}

API reference: Cancel Subscription

Change Plan

Moves a customer from their current plan to a different one. Use this when a customer upgrades, downgrades, or switches pricing tiers. You control when the change takes effect using the effective field:

`effective` value	What happens
`NEXT_CYCLE` (default)	The new plan is stored as pending and activates at the next successful billing cycle
`IMMEDIATELY`	The customer is switched to the new plan right now

effective defaults to NEXT_CYCLE if you leave it out. This is the safer option for most cases — the customer’s current billing period is honoured before the new plan kicks in.

curl --request POST \
  --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/change-plan \
  --header 'Authorization: Payaza <Public API Key encoded in base 64>' \
  --header 'Content-Type: application/json' \
  --data '{
    "newPlanCode": "PLN_DD41251",
    "effective": "NEXT_CYCLE",
    "prorate": true
  }'

curl --request POST \
  --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/change-plan \
  --header 'Authorization: Payaza <YOUR_PUBLIC_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'X-TenantID: test' \
  --data '{
    "newPlanCode": "PLN_DD41251",
    "effective": "IMMEDIATELY",
    "prorate": false
  }'

Path parameter

Parameter	Type	Description
`id`	Integer	The subscription ID to change the plan for

Body parameters

Parameter	Type	Required	Description
`newPlanCode`	String	✓	The `planCode` of the plan to switch to
`effective`	String	No	When to apply the change: `NEXT_CYCLE` or `IMMEDIATELY`. Defaults to `NEXT_CYCLE`
`prorate`	Boolean	No	Whether to prorate the current billing cycle when switching immediately. Only relevant when `effective: "IMMEDIATELY"`

Sample response

{
  "success": true,
  "message": "Plan change scheduled",
  "data": {
    "id": 20,
    "status": "ACTIVE",
    "pendingPlanId": 8,
    "nextChargeDate": "2026-07-30T10:00:00"
  }
}

API reference: Change Plan

Error handling

Scenario	What to check
Trying to resume a non-paused subscription	Only `PAUSED` subscriptions can be resumed. Check `status` via Get Subscription first
Trying to pause or change plan on a cancelled subscription	`CANCELLED` subscriptions are terminal — no further operations are possible
Changing to the current plan	Attempting to change to the same plan the customer is already on returns a validation error
`reason` missing on cancel	The `reason` field is required on the cancel endpoint

Developer notes

Use Pause when a customer needs a temporary break (e.g. a student on holiday). Billing resumes cleanly without needing to create a new subscription.
Use Cancel only when the customer’s subscription should permanently end. If there’s any chance they will return, Pause is the better choice.
Change Plan with NEXT_CYCLE is the safest option for upgrades/downgrades — it respects the customer’s paid billing window. Use IMMEDIATELY only when you need the change to take effect right away (e.g. an emergency downgrade).
pendingPlanId in the Change Plan response shows the new plan is queued but not yet active. The switch happens at the next billing cycle.
All lifecycle operations require the subscription id (integer), not the planCode. Keep a mapping of customer → subscription id in your database.

What’s next

Subscription Reads

View subscription details, charge history, upcoming charges, and the full event audit log.

Subscription Plans

Create or update the plans your customers subscribe to.

Get Started

Developer Tools

Accept Payments

Send Money

Disputes & Refunds

Account Management

Subscriptions

Split Settlements

Overview

Key Requirements

Pause a Subscription

Resume a Subscription

Cancel a Subscription

Change Plan

Error handling

Developer notes

What’s next

Subscription Reads

Subscription Plans

​Overview

​Key Requirements

​Pause a Subscription

​Resume a Subscription

​Cancel a Subscription

​Change Plan

​Error handling

​Developer notes

​What’s next

Subscription Reads

Subscription Plans

Overview

Key Requirements

Pause a Subscription

Resume a Subscription

Cancel a Subscription

Change Plan

Error handling

Developer notes

What’s next