# Cancel subscription

Cancels the subscription immediately or schedules cancellation for the end of the current billing period.

Endpoint: POST /subscriptions/cancel
Version: 2.0.0
Security: bearerAuth

## Request fields (application/json):

  - `channel_id` (string)
    Unique channel identifier. Required when using multi-channel API keys.
    Example: "chn_01JYWX6Z5A8P32B6NVH1G9876A"

  - `id` (string, required)
    Unique subscription identifier.
    Example: "subs_01HYDYBRKN16B8X3BR9WP78ZR7"

  - `mode` (string, required)
    Defines when the subscription is cancelled. Use NOW to cancel immediately or PERIOD_END to cancel at the end of the current billing period.
    Enum: "NOW", "PERIOD_END"

  - `comment` (string)
    Free-form reason for the cancellation.
    Example: "Customer requested cancellation"

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique subscription identifier.
    Example: "subs_01HYDYBRKN16B8X3BR9WP78ZR7"

  - `status` (string, required)
    Current subscription status.
    Enum: "CREATED", "PENDING", "TRIALING", "ACTIVE", "REDEMPTION", "UNPAID", "CANCELLED", "EXPIRED"

  - `currency` (string, required)
    Three-letter ISO-4217 currency code.
    Example: "USD"

  - `line_items` (array, required)
    Line items applied to the subscription.
    Example: [{"id":"slit_01KPWT0K1PQWEYYRT7J1H3NC85","billing_type":"RECURRING","currency":"USD","amount":1000,"quantity":1,"started_at":"2025-12-24T11:45:00.000000Z","period":{"start_at":"2025-12-24T11:45:00.000000Z","end_at":"2026-01-24T11:45:00.000000Z"},"billing_period_config":{"value":1,"unit":"MONTH"},"product_info":{"name":"Great product","description":"Annual subscription for a great product"},"created_at":"2025-12-24T11:45:00.000000Z","updated_at":"2025-12-24T11:47:00.000000Z","product_id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","product_price_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479"}]

  - `line_items.id` (string, required)
    Unique line item identifier.
    Example: "slit_01KPWT0K1PQWEYYRT7J1H3NC85"

  - `line_items.billing_type` (string, required)
    Billing type of the line item.
    Enum: "RECURRING", "ONE_TIME"

  - `line_items.currency` (string, required)
    Three-letter ISO-4217 currency code.
    Example: "USD"

  - `line_items.amount` (integer, required)
    Line item amount in minor units.
    Example: 1000

  - `line_items.quantity` (integer, required)
    Number of product units.
    Example: 1

  - `line_items.started_at` (string)
    Date and time when the line item started.
    Example: "2025-12-24T11:45:00.000000Z"

  - `line_items.period` (object)
    Billing period interval for the line item.
    Example: {"start_at":"2025-12-24T11:45:00.000000Z","end_at":"2026-01-24T11:45:00.000000Z"}

  - `line_items.period.start_at` (string, required)
    Date and time when the interval starts.
    Example: "2025-12-24T11:45:00.000000Z"

  - `line_items.period.end_at` (string, required)
    Date and time when the interval ends. Not present when the interval is open-ended and continues indefinitely.
    Example: "2026-01-24T11:45:00.000000Z"

  - `line_items.billing_period_config` (object)
    Recurring calendar interval at which the line item is billed.
    Example: {"value":1,"unit":"MONTH"}

  - `line_items.billing_period_config.value` (integer, required)
    Number of units in the period.
    Example: 1

  - `line_items.billing_period_config.unit` (string, required)
    Time unit for the period.
    Enum: "MINUTE", "HOUR", "DAY", "WEEK", "MONTH", "QUARTER", "YEAR"

  - `line_items.product_info` (object, required)
    Snapshot of product details for the line item.
    Example: {"name":"Great product","description":"Annual subscription for a great product"}

  - `line_items.product_info.name` (string, required)
    Product name.
    Example: "Great product"

  - `line_items.product_info.description` (string)
    Product description.
    Example: "Annual subscription for a great product"

  - `line_items.created_at` (string, required)
    Date and time when the line item was created.
    Example: "2025-12-24T11:45:00.000000Z"

  - `line_items.updated_at` (string, required)
    Date and time when the line item was updated.
    Example: "2025-12-24T11:47:00.000000Z"

  - `line_items.product_id` (string, required)
    Identifier of the associated product.
    Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"

  - `line_items.product_price_id` (string, required)
    Identifier of the associated price.
    Example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"

  - `created_at` (string, required)
    Date and time when the subscription was created.
    Example: "2025-12-24T11:45:00.000000Z"

  - `updated_at` (string, required)
    Date and time when the subscription was updated.
    Example: "2025-12-24T11:47:00.000000Z"

  - `started_at` (string)
    Date and time when the subscription started.
    Example: "2025-12-24T11:45:00.000000Z"

  - `next_billing_at` (string)
    Date and time when the next billing occurs.
    Example: "2026-01-24T11:45:00.000000Z"

  - `anchor_at` (string)
    Date and time used to anchor billing cycles.
    Example: "2025-12-24T11:45:00.000000Z"

  - `trial_info` (object)
    Trial details for the subscription.
    Example: {"type":"FREE","period":{"start_at":"2025-12-24T11:45:00.000000Z","end_at":"2025-12-31T11:45:00.000000Z"},"amount":0,"period_config":{"value":7,"unit":"DAY"}}

  - `trial_info.type` (string, required)
    Trial type.
    Enum: "FREE", "PAID"

  - `trial_info.period` (object)
    Trial period interval.
    Example: {"start_at":"2025-12-24T11:45:00.000000Z","end_at":"2026-01-24T11:45:00.000000Z"}

  - `trial_info.period.start_at` (string, required)
    Date and time when the interval starts.
    Example: "2025-12-24T11:45:00.000000Z"

  - `trial_info.period.end_at` (string, required)
    Date and time when the interval ends. Not present when the interval is open-ended and continues indefinitely.
    Example: "2026-01-24T11:45:00.000000Z"

  - `trial_info.amount` (integer, required)
    Trial amount in minor units.

  - `trial_info.period_config` (object)
    Period expressed as a numeric value and a time unit.
    Example: {"value":7,"unit":"DAY"}

  - `trial_info.period_config.value` (integer, required)
    Number of units in the period.
    Example: 7

  - `trial_info.period_config.unit` (string, required)
    Time unit for the period.
    Enum: same as `line_items.billing_period_config.unit` (7 values)

  - `cancellation_info` (object)
    Cancellation details for the subscription. Present when the subscription is scheduled for cancellation or already cancelled.
    Example: {"cancel_at":"2026-03-24T11:45:00.000000Z","requested_at":"2026-02-24T11:45:00.000000Z","reason":"CANCELLATION_REQUESTED","comment":"Customer requested cancellation"}

  - `cancellation_info.cancel_at` (string, required)
    Date and time when the subscription is scheduled to be cancelled or was cancelled.
    Example: "2026-03-24T11:45:00.000000Z"

  - `cancellation_info.requested_at` (string, required)
    Date and time when cancellation was requested.
    Example: "2026-02-24T11:45:00.000000Z"

  - `cancellation_info.reason` (string, required)
    Reason for the cancellation.
    Enum: "DUNNING_EXHAUSTED", "CANCELLATION_REQUESTED"

  - `cancellation_info.comment` (string)
    Additional cancellation comment.
    Example: "Customer requested cancellation"

  - `discounts` (array)
    Discounts applied to the subscription.
    Example: [{"coupon_id":"0291b87b-deac-4eb4-8732-2a70d247a171","coupon_code":"WINTER25"}]

  - `discounts.coupon_id` (string, required)
    Unique identifier of the associated coupon.
    Example: "0291b87b-deac-4eb4-8732-2a70d247a171"

  - `discounts.coupon_code` (string)
    Code of the associated coupon.
    Example: "WINTER25"

  - `metadata` (object)
    Set of key-value pairs attached to the subscription.
    Example: {"order_id":"12345"}

  - `description` (string)
    Additional description for the subscription.
    Example: "Premium plan subscription"

  - `customer_id` (string, required)
    Unique customer identifier.
    Example: "cust_01KMG2ABYPF6XS5DMJQ817C429"

  - `payment_instrument_id` (string)
    Identifier of the payment instrument used for billing.
    Example: "pi_01J1Z2X3Y4W5V6U7T8S9R0"

  - `latest_invoice_id` (string)
    Identifier of the most recent invoice.
    Example: "inv_01KPWT0K1PQWEYYRT7J1H3NC85"

## Response 400 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "VALIDATION"

  - `message` (string, required)
    Message describing the error.
    Example: "One or more fields failed validation due to constraints"

  - `context` (object, required)
    Additional context about the validation error, including specific constraints.
    Example: {"constraints":{"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}}

  - `context.constraints` (object, required)
    Failed constraints keyed by the field name.
    Example: {"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}

## Response 401 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "UNAUTHENTICATED"

  - `message` (string, required)
    Message describing the error.
    Example: "Credentials are invalid or missing"

## Response 403 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "PERMISSION_DENIED"

  - `message` (string, required)
    Message describing the error.
    Example: "Permission denied"

## Response 404 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "NOT_FOUND"

  - `message` (string, required)
    Message describing the error. The entity varies by endpoint.
    Example: "The requested resource could not be found"

## Response 422 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "INCOMPATIBLE_STATUS", "SCHEDULED_FOR_CANCELLATION"

  - `message` (string, required)
    Message describing the error.
    Example: "The request conflicts with the current state"

  - `context` (object)
    Additional error context.

## Response 429 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "RATE_LIMIT"

  - `message` (string, required)
    Message describing the error.
    Example: "Rate limit exhausted"

  - `context` (object)
    Additional context about the error.

  - `context.next_try_at` (string)
    Timestamp indicating when to retry the request.
    Example: "2024-12-31T23:59:59.000000Z"