---
title: "Cancel subscription"
description: "Cancels a subscription at the end of its period, or at once when every payment of it was refunded."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel subscription

Needs the subscription:write scope.

## Call

- Tool: `cancel_subscription`
- Scope: `subscription:write`
- Writes, and may change or remove what is there.
- Acts on a store.

## Arguments

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `subscription` | `object` | Yes |  |
| `reason` | `string` | No | Why, in your own words; one of the codes the store writes itself as a reason (`refund`, `dispute`, `upgraded`, `account_erased`, `Ended by the seller.` and the like) is refused. |

```json
{
  "type": "object",
  "properties": {
    "subscription": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        }
      },
      "required": [
        "id"
      ],
      "additionalProperties": false
    },
    "reason": {
      "description": "Why, in your own words; one of the codes the store writes itself as a reason (`refund`, `dispute`, `upgraded`, `account_erased`, `Ended by the seller.` and the like) is refused.",
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    }
  },
  "required": [
    "subscription"
  ],
  "additionalProperties": false
}
```

## Answer

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `display_status` | `string` | Yes | Its status as people read it: `cancelling` while it bills and is set to stop. |
| `next_event` | `object or null` | Yes | What happens at the end of its latest paid period, as of the answer; null when nothing is ahead. |
| `renews_on_card` | `boolean` | Yes | Whether the store holds its saved card for its renewals: billed here, renewing and not set to stop. |
| `actions` | `object` | Yes | The moves the store offers on it as of the answer, billed here and still renewing; a write still decides again. |
| `plan_changes` | `array of object` | Yes | The prices `changeSubscriptionPlan` schedules for it, ordered as offers are; empty unless `actions.change_plan`. |
| `product` | `object or null` | Yes |  |
| `plan` | `object or null` | Yes |  |
| `current_period` | `object or null` | Yes | Its latest paid period, whose end is when the next payment is due; null when none is paid. |
| `next_charge` | `object or null` | Yes | What its next payment charges and when, a day ahead of the period's end as every renewal is, on the plan it renews on; null unless it renews. A `current_period` that is a `lead_in` makes it the first. |
| `instrument_id` | `string or null` | Yes | The saved payment method its renewals charge, as `getBillingProfile` names it. |
| `renews_here` | `boolean` | Yes | Whether the store bills it here, so its plan and card can change. |
| `scheduled_change` | `object or null` | Yes | The plan it renews on from `effective_at`, the end of its paid run, as the customer scheduled; null for none. |
| `id` | `string` | Yes |  |
| `product_id` | `string` | Yes |  |
| `status` | `string` | Yes |  |
| `cancel_at_period_end` | `boolean` | Yes |  |
| `cancel_reason` | `string or null` | Yes | Why it stops or stopped, in the seller's or the customer's own words; null when no one gave one. |
| `cancel_code` | `string or null` | Yes | How the store stopped it, when no one gave a reason in words: `refund` (its payments were refunded), `dispute` (a payment was disputed), `upgraded` (an upgrade replaced it), `account_erased` (the customer's account was erased) or `seller_ended` (the seller ended it); null otherwise. |
| `created_at` | `string or null` | Yes |  |
| `ended_at` | `string or null` | Yes |  |

The answer's full shape is on [its API reference page](/customer-api/reference/cancel-subscription).

Source: https://docs.sherpo.io/customer-mcp/tools/cancel_subscription/index.mdx
