# Cancel subscription

Cancels the <a href="https://docs.solidgate.com/billing/subscriptions/subscriptions-2.0/" target="_blank">subscription</a> 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.000…

  - `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.

  - `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: e6f26db1-f633-4723-ab08-50ddee7bc648

  - `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

  - `start_scheduled_at` (string)
    Date and time when the subscription is scheduled to start. Present only while the subscription is in the `CREATED` status and matches the `starts_at` value from the create request.
    Example: 2026-01-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.

  - `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.
    Example: 0

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

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

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

  - `cancellation_info` (object)
    Cancellation details for the subscription. Present when the subscription is scheduled for cancellation or already cancelled.

  - `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", "FRAUD_ALERT_RECEIVED", "DISPUTE_RECEIVED"

  - `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

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

  - `merchant_reference` (string)
    Merchant-defined reference for the subscription.
    Example: premium-plan-subs-482

  - `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"}}}

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

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