Cancel Subscription

POST/subscriptions/:subscriptionId/cancel

Description

Cancel an active subscription. By default, the subscription remains active until the end of the current billing period. You can optionally cancel immediately.

📅

When cancelled at period end, the customer retains access until their current billing period expires. Use cancel_immediately to revoke access right away.

Headers

Header	Description	Required
Authorization	Bearer token with your API key	yes
Content-Type	application/json	yes (if sending body)

Path Parameters

Name	Type	Description	Required
subscriptionId	string	The unique identifier of the subscription to cancel.	yes

Request Body

Name	Type	Description	Required
cancel_immediately	boolean	If true, cancels immediately. If false, cancels at period end (default: false).	no
reason	string	Optional reason for cancellation for your records.	no

Example Request

Cancel at Period End (Default)

const response = await fetch(
  'https://checkout.exodus.com/subscriptions/sub_1234567890abcdef/cancel',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
    },
  }
);

Cancel Immediately

const response = await fetch(
  'https://checkout.exodus.com/subscriptions/sub_1234567890abcdef/cancel',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      cancel_immediately: true,
      reason: 'Customer requested immediate cancellation',
    }),
  }
);

Response

Cancelled at Period End

CANCELLED AT PERIOD END

{
  "id": "sub_1234567890abcdef",
  "object": "subscription",
  "amount": 2999,
  "currency": "USD",
  "interval": "monthly",
  "name": "Pro Plan",
  "status": "active",
  "cancel_at_period_end": true,
  "customer_id": "cus_0987654321fedcba",
  "customer_email": "[email protected]",
  "current_period_start": "2024-01-29T12:00:00Z",
  "current_period_end": "2024-02-29T12:00:00Z",
  "cancellation_reason": null,
  "metadata": {
    "plan_id": "pro_monthly"
  },
  "created_at": "2024-01-15T12:00:00Z"
}

Cancelled Immediately

CANCELLED IMMEDIATELY

{
  "id": "sub_1234567890abcdef",
  "object": "subscription",
  "amount": 2999,
  "currency": "USD",
  "interval": "monthly",
  "name": "Pro Plan",
  "status": "cancelled",
  "cancel_at_period_end": false,
  "customer_id": "cus_0987654321fedcba",
  "customer_email": "[email protected]",
  "current_period_start": "2024-01-29T12:00:00Z",
  "current_period_end": "2024-02-29T12:00:00Z",
  "cancellation_reason": "Customer requested immediate cancellation",
  "cancelled_at": "2024-02-15T10:30:00Z",
  "metadata": {
    "plan_id": "pro_monthly"
  },
  "created_at": "2024-01-15T12:00:00Z"
}

Error Responses

INVALID STATUS

{
  "error": {
    "type": "invalid_request",
    "message": "Subscription is already cancelled"
  }
}

NOT FOUND

{
  "error": {
    "type": "not_found",
    "message": "Subscription not found"
  }
}