> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Cancel Preview
> The deterministic financial consequence of canceling a subscription — effective date, resulting status, deferred revenue forfeited, and future billing avoided — shown before the mutation.
Returns the deterministic financial forecast of canceling a subscription,
shown **before** the mutation so an operator never cancels blind. The
[cancel](/api-reference/subscriptions/cancel) mutation itself is unchanged —
this endpoint only reads.
It exposes exactly what the engine computes deterministically:
* **`effective_date`** and **`resulting_status`** — when the cancel would take
effect and the status it leaves the subscription in.
* **`deferred_revenue_forfeited`** / **`recognized_as_breakage`** — the
still-deferred revenue an *immediate* cancel forfeits and recognizes as
breakage, computed read-only from the same revenue-recognition data the
mutation uses.
* **`avoided_future_recurring`** — the future recurring amount that will no
longer bill.
* **`flat_fee_refund`** — always `0`: the flat fee is paid in advance and is
not refunded.
It deliberately **omits** an unused-time proration credit (the cancel mutation
posts none) and a final metered-usage figure (only the mutating invoice path
can produce one). See [Explain any number](/advanced/explain-any-number).
## Query Parameters
| Parameter | Type | Required | Description |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------- |
| `immediately` | boolean | No | Preview an immediate cancel (`true`) vs cancel-at-period-end (default `false`). |
## Example Request
```bash theme={null}
curl "https://api.recurso.dev/v1/subscriptions/b9071c55-0e14-4720-80f3-665613ceb7de/cancel-preview?immediately=true" \
-H "Authorization: Bearer $API_KEY"
```
## Response
```json theme={null}
{
"data": {
"subscription_id": "b9071c55-0e14-4720-80f3-665613ceb7de",
"immediately": true,
"effective_date": "2026-08-18T10:30:00Z",
"resulting_status": "canceled",
"cancel_at_period_end": false,
"currency": "USD",
"deferred_revenue_forfeited": 45161,
"recognized_as_breakage": 45161,
"avoided_future_recurring": 100000,
"flat_fee_refund": 0
}
}
```
## Fields
| Field | Type | Description |
| ---------------------------- | ------------------ | ---------------------------------------------------------------- |
| `immediately` | boolean | The mode that was previewed |
| `effective_date` | string (date-time) | When the cancel would take effect |
| `resulting_status` | string | The status the subscription would end up in |
| `cancel_at_period_end` | boolean | `true` when the preview is a period-end cancel |
| `currency` | string | Currency of the amounts below |
| `deferred_revenue_forfeited` | integer (int64) | Still-deferred revenue an immediate cancel forfeits, minor units |
| `recognized_as_breakage` | integer (int64) | The portion recognized as breakage on cancel |
| `avoided_future_recurring` | integer (int64) | Future recurring amount that will no longer bill |
| `flat_fee_refund` | integer (int64) | Always `0` — flat fee paid in advance, not refunded |
Read-only and side-effect free — nothing is posted, scheduled, or changed. A
missing or cross-tenant `id` returns `404`.
## OpenAPI
````yaml GET /v1/subscriptions/{id}/cancel-preview
openapi: 3.1.0
info:
title: Recurso API
version: 1.0.0
description: |
The Recurso billing engine REST API.
Authenticate by passing your API key as a bearer token:
Authorization: Bearer
Obtain an API key by registering a tenant via `POST /auth/register`.
All authenticated endpoints live under the `/v1` prefix. Mutating
endpoints support idempotency via the `Idempotency-Key` header.
license:
name: MIT
identifier: MIT
servers:
- url: https://billing.example.com
description: >-
Example deployment — substitute the base URL of your own Recurso
deployment.
security:
- bearerAuth: []
tags:
- name: System
description: Health, version, and API metadata
- name: Auth
description: Tenant registration
- name: Plans
description: Product catalog plans
- name: Customers
description: Customer management
- name: Subscriptions
description: Subscription lifecycle
- name: Invoices
description: Invoices, PDFs, and Indian GST e-invoicing
- name: Coupons
description: Discounts
- name: Usage
description: Metered usage events
- name: Credit Notes
description: Customer credits
- name: Quotes
description: Quote-to-invoice lifecycle
- name: Webhooks
description: Webhook endpoint management and event feed
- name: Analytics
description: Revenue analytics
- name: Checkout
description: Public hosted checkout for invoices
- name: Payments
description: Payment order creation
- name: Inbound Webhooks
description: Receivers for payment-gateway callbacks (Razorpay, Stripe)
- name: Customer Portal
description: Customer-facing portal — magic-link auth and session-scoped data
- name: Developer
description: API key management
- name: Account
description: Tenant account settings
- name: Finance
description: Ledger accounts, entries, reconciliation, and revenue recognition
- name: Settings
description: Tax (GST) and e-invoicing (IRP) configuration
- name: Consents
description: Consent records for RBI-compliant recurring billing
- name: Referrals
description: Customer referral program
- name: Gifts
description: Gift subscriptions
- name: Mandates
description: UPI Autopay mandates
- name: Offline Payments
description: Virtual accounts and manually recorded payments
- name: Organizations
description: Multi-entity organizations grouping several tenants
- name: Accounting
description: QuickBooks / Xero accounting integrations
- name: Churn
description: Churn risk scoring and alerts
- name: Cancel Flows
description: Configurable retention flows shown at cancellation time
- name: Dunning
description: Dunning analytics and multi-channel dunning campaigns
paths:
/v1/subscriptions/{id}/cancel-preview:
get:
tags:
- Subscriptions
summary: Preview the financial consequence of a cancellation
description: >
The deterministic financial forecast of canceling a subscription, shown
BEFORE the mutation so an operator never cancels blind. Exposes only
what the engine computes deterministically: effective time + resulting
status, the still-deferred revenue an immediate cancel forfeits and
recognizes as breakage (computed read-only from the same rev-rec data
the mutation uses), the future recurring amount that will no longer
bill, and flat_fee_refund (constant 0 — the flat fee is paid in advance,
not refunded). It deliberately omits an unused-time proration credit
(the cancel mutation posts none) and a final metered-usage figure (only
the mutating invoice path can produce it). The cancel mutation is
unchanged. Read-only; cross-tenant ids return 404.
operationId: getSubscriptionCancelPreview
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: immediately
in: query
required: false
schema:
type: boolean
default: false
description: >-
Preview an immediate cancel (true) vs cancel-at-period-end
(default).
responses:
'200':
description: The cancel preview.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
subscription_id:
type: string
format: uuid
immediately:
type: boolean
effective_date:
type: string
format: date-time
resulting_status:
type: string
cancel_at_period_end:
type: boolean
currency:
type: string
deferred_revenue_forfeited:
type: integer
format: int64
recognized_as_breakage:
type: integer
format: int64
avoided_future_recurring:
type: integer
format: int64
flat_fee_refund:
type: integer
format: int64
description: Always 0 — flat fee paid in advance
not refunded.: null
'404':
description: Subscription not found.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: >-
Tenant API key obtained from `POST /auth/register` or `POST
/v1/developer/keys`.
````