> ## 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 Lifecycle > Manage active subscriptions — pause billing, resume it, cancel permanently, or move a customer to a different plan. ## 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](/guides/authentication) page. Use your **public API key** for all lifecycle requests. Set the following headers on every request: ```json theme={null} { "Authorization": "Payaza " } ``` *** ## 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. ```bash cURL — Pause with auto-resume date theme={null} curl --request PATCH \ --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/pause \ --header 'Authorization: Payaza ' \ --header 'Content-Type: application/json' \ --data '{ "resumeAt": "2026-08-01T00:00:00" }' ``` ```bash cURL — Pause indefinitely (manual resume required) theme={null} curl --request PATCH \ --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/pause \ --header 'Authorization: Payaza Payaza ' \ --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** ```json theme={null} { "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](/api-reference/subscription-lifecycle/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. ```bash cURL theme={null} curl --request PATCH \ --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/resume \ --header 'Authorization: Payaza ' \ ``` **Sample response** ```json theme={null} { "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](/api-reference/subscription-lifecycle/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. ```bash cURL theme={null} curl --request PATCH \ --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/cancel \ --header 'Authorization: Payaza ' \ --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** ```json theme={null} { "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](/api-reference/subscription-lifecycle/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. ```bash cURL — Change at next cycle (upgrade/downgrade) theme={null} curl --request POST \ --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/change-plan \ --header 'Authorization: Payaza ' \ --header 'Content-Type: application/json' \ --data '{ "newPlanCode": "PLN_DD41251", "effective": "NEXT_CYCLE", "prorate": true }' ``` ```bash cURL — Change immediately theme={null} curl --request POST \ --url https://api.payaza.africa/live/subscription/api/v1/subscriptions/20/change-plan \ --header 'Authorization: Payaza ' \ --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** ```json theme={null} { "success": true, "message": "Plan change scheduled", "data": { "id": 20, "status": "ACTIVE", "pendingPlanId": 8, "nextChargeDate": "2026-07-30T10:00:00" } } ``` **API reference:** [Change Plan](/api-reference/subscription-lifecycle/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](/guides/subscription-reads) 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 View subscription details, charge history, upcoming charges, and the full event audit log. Create or update the plans your customers subscribe to.