> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Cancel subscription
> Cancel a subscription by ID — at the end of the billing cycle by default, or immediately
By default the cancellation is **scheduled for the end of the current billing cycle**. The subscription stays active until its renewal date (`ends_at`) and then transitions to `canceled` — the customer keeps access to what they have already paid for, and no further invoices are generated.
Pass `immediate: true` to cancel right away. The subscription is set to `canceled` immediately and `cancelled_at` is populated. Free-plan and in-trial subscriptions are always cancelled immediately, regardless of the `immediate` flag, since there is no paid period to honour.
The success `message` reflects what happened: `"Cancellation scheduled successfully. Ends at ..."` when scheduled, or `"Subscription canceled successfully"` when cancelled immediately.
Changed your mind? Use `POST /api/v1/subscriptions/{subscription_id}/revert-cancellation` to undo a scheduled cancellation before its `ends_at` date is reached.
## OpenAPI
````yaml POST /api/v1/subscriptions/{subscription_id}/schedule-cancellation
openapi: 3.0.1
info:
title: Metrifox API Documentation
version: v1
description: >-
Welcome to Metrifox Platform's API documentation. This comprehensive API
suite enables seamless integration with our platform, providing secure and
efficient access to our services.
servers:
- url: https://{defaultHost}
variables:
defaultHost:
default: api.metrifox.com
security:
- api_key: []
paths:
/api/v1/subscriptions/{subscription_id}/schedule-cancellation:
post:
tags:
- Subscriptions
summary: Cancel a subscription
description: >
Cancels a subscription by its ID.
By default the cancellation is **scheduled for the end of the current
billing cycle**: the
subscription stays active until its renewal date (returned as `ends_at`)
and then transitions
to `canceled`. The customer keeps access to everything they have already
paid for, and no
further invoices are generated.
Pass `immediate: true` to cancel **right away** instead — the
subscription is set to `canceled`
immediately and `cancelled_at` is populated. Note that free-plan and
in-trial subscriptions are
always cancelled immediately regardless of the `immediate` flag, since
there is no paid period
to honour.
Inspect the `status` and `message` fields in the response to tell
whether the subscription was
scheduled or cancelled immediately. To undo a scheduled cancellation
before it takes effect, use
`POST /api/v1/subscriptions/{subscription_id}/revert-cancellation`.
operationId: scheduleSubscriptionCancellation
parameters:
- name: subscription_id
in: path
required: true
description: The unique subscription identifier (UUID)
schema:
type: string
format: uuid
example: 625f5cee-259b-4994-b7eb-416b9e551f2c
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
immediate:
type: boolean
default: false
description: >
When `false` (default), the subscription is scheduled to
cancel at the end of the
current billing cycle and `ends_at` is set to the renewal
date. When `true`, the
subscription is cancelled immediately.
responses:
'200':
description: Subscription cancelled or scheduled for cancellation
content:
application/json:
schema:
type: object
properties:
statusCode:
type: integer
example: 200
message:
type: string
meta:
type: object
data:
type: object
description: The updated subscription
errors:
type: object
examples:
scheduled:
summary: >-
Scheduled for end of billing cycle (immediate omitted or
false)
value:
statusCode: 200
message: >-
Cancellation scheduled successfully. Ends at 2026-07-01
00:00:00 UTC
meta: {}
data:
id: 625f5cee-259b-4994-b7eb-416b9e551f2c
status: active
starts_at: '2026-06-01T00:00:00.000Z'
ends_at: '2026-07-01T00:00:00.000Z'
renews_at: '2026-07-01T00:00:00.000Z'
cancelled_at: null
currency_code: USD
billing_interval: monthly
errors: {}
immediate:
summary: >-
Cancelled immediately (immediate true, free plan, or
in-trial)
value:
statusCode: 200
message: Subscription canceled successfully
meta: {}
data:
id: 625f5cee-259b-4994-b7eb-416b9e551f2c
status: canceled
starts_at: '2026-06-01T00:00:00.000Z'
ends_at: '2026-06-15T13:01:32.715Z'
renews_at: '2026-07-01T00:00:00.000Z'
cancelled_at: '2026-06-15T13:01:32.715Z'
currency_code: USD
billing_interval: monthly
errors: {}
'400':
description: >
Bad request — the subscription is inactive, or it already has a
pending scheduled change
that must be cancelled first.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 400
message: Can not schedule cancellation for an inactive subscription
errors: {}
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Subscription not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 404
message: Subscription not found
errors:
subscription_id:
- >-
Subscription with ID
'625f5cee-259b-4994-b7eb-416b9e551f2c' does not exist
x-codeSamples:
- lang: curl
label: cURL (scheduled)
source: >
# Schedule cancellation for the end of the billing cycle (default)
curl -X POST
https://api.metrifox.com/api/v1/subscriptions/625f5cee-259b-4994-b7eb-416b9e551f2c/schedule-cancellation
\
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json"
- lang: curl
label: cURL (immediate)
source: >
# Cancel immediately
curl -X POST
https://api.metrifox.com/api/v1/subscriptions/625f5cee-259b-4994-b7eb-416b9e551f2c/schedule-cancellation
\
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{ "immediate": true }'
components:
schemas:
ErrorResponse:
type: object
properties:
message:
type: string
description: Error message
errors:
type: object
additionalProperties: true
description: Detailed error information
securitySchemes:
api_key:
type: apiKey
name: x-api-key
in: header
````