Cancel Subscription

Cancel a subscription. Use when a customer churns or downgrades. Supports immediate or end-of-period cancellation with optional proration.

PUT /v1/subscriptions/{id}/cancel

Cancel Subscription

cURL

curl --request PUT \
  --url https://api.example.com/v1/subscriptions/{id}/cancel \
  --header 'Content-Type: application/json' \
  --data '
{
  "cancellation_type": "<string>",
  "proration_behavior": "<string>",
  "cancel_immediately_inovice_policy": "<string>",
  "reason": "<string>"
}
'

200

{
  "subscription_id": "<string>",
  "cancellation_type": "<string>",
  "effective_date": "<string>",
  "status": "<string>",
  "reason": "<string>",
  "proration_invoice": {},
  "proration_details": [
    {
      "line_item_id": "<string>",
      "price_id": "<string>",
      "plan_name": "<string>",
      "original_amount": "<string>",
      "credit_amount": "<string>",
      "charge_amount": "<string>",
      "proration_days": 123,
      "description": "<string>"
    }
  ],
  "total_credit_amount": "<string>",
  "message": "<string>",
  "processed_at": "<string>"
}

Path Parameters

id · string · required

Unique identifier of the subscription to cancel.

Example: "sub_x1y2z3a4b5c6d7e8f9g0"

Request Body

cancellation_type · string · required

When the cancellation takes effect.

Options:

• "IMMEDIATE" - Cancel immediately
• "END_OF_PERIOD" - Cancel at the end of the current billing period

proration_behavior · string · default: "NONE"

How to handle proration when cancelling.

Options:

• "NONE" - No proration
• "CREATE_PRORATIONS" - Generate proration credits/charges

cancel_immediately_inovice_policy · string · default: "SKIP"

Whether to generate a final invoice on immediate cancellation.

Options:

• "SKIP" - Do not generate invoice
• "GENERATE" - Generate final invoice

reason · string

Reason for cancellation (for audit and business intelligence).

Example: "Customer requested cancellation"

Response

subscription_id · string

ID of the cancelled subscription.

cancellation_type · string

Type of cancellation performed.

effective_date · string

ISO 8601 timestamp when the cancellation takes effect.

status · string

New status of the subscription.

Values: "CANCELLED", "ACTIVE" (if cancelling at period end)

reason · string

Reason for cancellation (if provided).

proration_invoice · object

Proration invoice details (if proration was applied).

proration_details · array

Array of line-item level proration information.

Show proration_details properties

line_item_id · string

Line item ID.

price_id · string

Price ID.

plan_name · string

Plan name.

original_amount · string

Original amount (decimal as string).

credit_amount · string

Credit amount (decimal as string).

charge_amount · string

Charge amount (decimal as string).

proration_days · integer

Number of days used for proration calculation.

description · string

Description of the proration.

total_credit_amount · string

Total credit amount from proration (decimal as string).

message · string

Human-readable message about the cancellation.

processed_at · string

ISO 8601 timestamp when the cancellation was processed.

Example Request - Immediate Cancellation

cURL

curl --request PUT \
  --url https://api.flexprice.io/v1/subscriptions/sub_x1y2z3a4b5c6d7e8f9g0/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "cancellation_type": "IMMEDIATE",
    "proration_behavior": "CREATE_PRORATIONS",
    "reason": "Customer requested cancellation"
  }'

Example Request - End of Period Cancellation

cURL

curl --request PUT \
  --url https://api.flexprice.io/v1/subscriptions/sub_x1y2z3a4b5c6d7e8f9g0/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "cancellation_type": "END_OF_PERIOD",
    "reason": "Customer requested to cancel at end of billing period"
  }'

Example Response - Immediate Cancellation with Proration

{
  "subscription_id": "sub_x1y2z3a4b5c6d7e8f9g0",
  "cancellation_type": "IMMEDIATE",
  "effective_date": "2024-03-25T14:30:00Z",
  "status": "CANCELLED",
  "reason": "Customer requested cancellation",
  "proration_invoice": {
    "id": "inv_proration123",
    "amount_due": "-25.00",
    "currency": "usd"
  },
  "proration_details": [
    {
      "line_item_id": "li_abc123",
      "price_id": "price_xyz789",
      "plan_name": "Pro Plan",
      "original_amount": "99.00",
      "credit_amount": "25.00",
      "charge_amount": "0.00",
      "proration_days": 8,
      "description": "Credit for unused time (March 25-31)"
    }
  ],
  "total_credit_amount": "25.00",
  "message": "Subscription cancelled successfully with proration credit applied",
  "processed_at": "2024-03-25T14:30:15Z"
}

Example Response - End of Period Cancellation

{
  "subscription_id": "sub_x1y2z3a4b5c6d7e8f9g0",
  "cancellation_type": "END_OF_PERIOD",
  "effective_date": "2024-04-20T00:00:00Z",
  "status": "ACTIVE",
  "reason": "Customer requested to cancel at end of billing period",
  "proration_details": [],
  "total_credit_amount": "0.00",
  "message": "Subscription will be cancelled at the end of the current period",
  "processed_at": "2024-03-25T14:30:15Z"
}