Cancel subscription

POST

api

subscriptions

{subscription_id}

schedule-cancellation

# 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"

{
  "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": {}
}

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.

Authorizations

x-api-key

string

header

required

Path Parameters

subscription_id

string<uuid>

required

The unique subscription identifier (UUID)

Body

application/json

immediate

boolean

default:false

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.

Response

Subscription cancelled or scheduled for cancellation

statusCode

integer

Example:

200

message

string