> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Pause and Resume a Subscription
> Pause a subscription to stop billing temporarily without cancelling it. Resume billing from a paused or suspended state with a single API call.
Pausing a subscription stops all renewal attempts without cancelling it, preserving the subscription record and all its history. Resuming restores billing and recalculates the next billing date forward from the current date — the customer is not charged for time elapsed while paused.
## Pause a Subscription
`POST /subscription/{id}/pause` suspends billing on an active subscription. It fires the `subscription.paused` webhook event and moves the subscription to `paused` status.
Only subscriptions in `active`, `trialing`, or `past_due` status can be paused. Attempting to pause a `cancelled`, `completed`, or already `paused` subscription returns a `400` error.
### Example
```bash theme={"dark"}
curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/pause \
-H "Authorization: Bearer prv_production_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "merchantCode": "MERCHANT_001" }'
```
***
## Resume a Subscription
`POST /subscription/{id}/resume` restores billing on a paused or suspended subscription, with slightly different behavior depending on the current status.
| Current status | Behavior on resume |
| -------------- | ------------------------------------------------------------------------- |
| `paused` | Billing restored. Next billing date = today + plan interval. |
| `suspended` | Therius attempts an immediate re-charge (MIT). Returns `402` if declined. |
If resuming from `suspended` returns `402` (card declined), you must first update the payment method using `POST /subscription/{id}/payment-method` before retrying the resume.
On success, Therius fires `subscription.resumed`. If a `suspended` subscription is revived by a successful charge, it also fires `subscription.reactivated`.
### Errors
| Code | Meaning |
| ----- | -------------------------------------------------------------------------------- |
| `400` | Subscription is not in a resumable state (e.g. already `active` or `cancelled`). |
| `402` | Resume from `suspended` failed — immediate re-charge was declined. |
| `404` | Subscription not found. |
### Example
```bash theme={"dark"}
curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/resume \
-H "Authorization: Bearer prv_production_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "merchantCode": "MERCHANT_001" }'
```
```bash cURL theme={"dark"}
curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/pause \
-H "Authorization: Bearer prv_production_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "merchantCode": "MERCHANT_001" }'
```
```json 200 OK theme={"dark"}
{}
```
## OpenAPI
````yaml POST /subscription/{id}/pause
openapi: 3.1.0
info:
title: Therius API
description: REST API for payments, subscriptions, and billing plans.
version: 1.0.0
servers:
- url: https://api.therius.io/v1
description: Production
- url: https://api-sandbox.therius.io/v1
description: Sandbox
security:
- bearerAuth: []
paths:
/subscription/{id}/pause:
post:
tags:
- Subscriptions
summary: Pause a subscription
operationId: pauseSubscription
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- merchantCode
properties:
merchantCode:
type: string
description: >-
Your merchant account identifier. Validated against the
Bearer key's merchant.
responses:
'200':
description: Subscription paused
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
components:
schemas:
Subscription:
type: object
description: >-
A customer enrollment in a plan. `plan` is embedded on
single-subscription responses. Invoice/event history is not included
here - use the invoice endpoints.
properties:
id:
type: string
description: Subscription UUID.
merchantId:
type: integer
description: The merchant account that owns the subscription.
planId:
type: integer
description: ID of the plan this subscription is enrolled in.
customerEmail:
type: string
description: Subscriber email, used for billing and dunning notifications.
customerName:
type: string
description: Subscriber name as it appears on invoices.
customerDocument:
type: string
description: >-
Subscriber national ID / tax document, where a market requires it
(e.g. Brazil CPF/CNPJ).
cardBrand:
type: string
description: Brand of the card on the mandate, e.g. `visa`.
status:
type: string
enum:
- pending
- trialing
- active
- past_due
- suspended
- paused
- cancelled
- completed
description: >-
`pending` - awaiting first charge; `trialing` - in a free trial;
`active` - billing normally; `past_due` - a renewal failed and
dunning is running; `suspended` - dunning exhausted, needs a new CIT
(`POST /subscription/{id}/payment-method` in CIT mode) to recover;
`paused` - billing stopped on request, resumable; `cancelled` -
terminated; `completed` - reached `maxBillingCycles`.
currentPeriodStart:
type: string
format: date-time
description: Start of the current billing period.
currentPeriodEnd:
type: string
format: date-time
description: End of the current billing period.
nextBillingDate:
type: string
format: date-time
description: When the next renewal charge is scheduled.
trialStart:
type: string
format: date-time
description: Trial start, when the plan has a trial.
trialEnd:
type: string
format: date-time
description: Trial end - the first real charge date.
dunningAttemptCount:
type: integer
description: Failed-renewal retry attempts made in the current dunning sequence.
activatedAt:
type: string
format: date-time
description: When the subscription first became `active`.
cancelledAt:
type: string
format: date-time
pausedAt:
type: string
format: date-time
suspendedAt:
type: string
format: date-time
startAt:
type: string
format: date-time
description: Deferred start, when creation set a future `startAt`.
cyclesCompleted:
type: integer
description: Number of billing cycles charged so far.
completedAt:
type: string
format: date-time
description: When the subscription reached `maxBillingCycles`.
parentSubscriptionId:
type: string
description: Parent subscription UUID, for add-on hierarchies.
propagateLifecycle:
type: boolean
description: Whether pause/cancel on the parent cascades to this subscription.
pendingPlanId:
type: integer
description: >-
Plan the subscription will switch to at the next cycle, set by a
`next_billing` change-plan.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
plan:
$ref: '#/components/schemas/Plan'
Plan:
type: object
description: >-
A reusable billing plan. `amount` is a flat integer in the currency
minor units (with separate `currency` + `exponent`) - not an Amount
object.
properties:
id:
type: integer
description: The plan unique integer ID.
merchantId:
type: integer
description: The merchant account that owns the plan.
name:
type: string
description:
type: string
interval:
type: string
enum:
- day
- week
- month
- year
description: Billing interval unit. Immutable after creation.
intervalCount:
type: integer
description: >-
Number of `interval` units between charges - `month` + `3` bills
quarterly.
amount:
type: integer
description: >-
Recurring charge in the currency minor units (e.g. `2999` = $29.99
at exponent 2). Immutable after creation.
currency:
type: string
description: ISO 4217 currency code. Immutable after creation.
exponent:
type: integer
description: >-
Decimal places for `amount` / `introAmount` - `2` for USD, `0` for
JPY.
trialPeriodDays:
type: integer
description: Free-trial length in days before the first charge. `0` for no trial.
introAmount:
type: integer
description: >-
Introductory charge in minor units for the first
`introBillingCycles` cycles, if set.
introBillingCycles:
type: integer
description: >-
How many initial cycles are billed at `introAmount` before the rate
reverts to `amount`.
maxBillingCycles:
type: integer
description: >-
Total cycles after which the subscription auto-completes. `0` =
open-ended.
availableCountries:
type: array
items:
type: string
description: >-
ISO 3166-1 alpha-2 codes the plan is offered in. Empty = available
everywhere.
isActive:
type: boolean
description: >-
Whether the plan accepts new subscribers. Existing subscriptions are
unaffected when this is `false`.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
prv_sandbox_xxx` (sandbox).
````