> ## 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.
# Cancel a Subscription
> Immediately cancel a subscription. Fires the subscription.cancelled webhook event. Cannot be undone.
`POST /subscription/{id}/cancel` immediately cancels a subscription. This action fires the `subscription.cancelled` webhook event and cannot be undone — the subscription moves to `cancelled` status permanently. If you want to stop billing temporarily without losing the subscription, use [Pause & Resume](/api-reference/subscriptions/pause-resume) instead.
Cancellation is permanent. There is no reinstate endpoint. If you need to re-enroll a cancelled customer, create a new subscription using `POST /subscription`.
Returns `200 OK` with the updated subscription object — `status: "cancelled"` and `cancelledAt` set.
## Errors
| Code | Meaning |
| ----- | ---------------------------------- |
| `400` | Subscription is already cancelled. |
| `404` | Subscription not found. |
```bash cURL theme={"dark"}
curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/cancel \
-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}/cancel
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}/cancel:
post:
tags:
- Subscriptions
summary: Cancel a subscription
operationId: cancelSubscription
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: Cancellation confirmed
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).
````