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

# Cancel Subscription

Cancels an active subscription, either immediately or at the end of the billing period.

## Mutation

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation CancelSubscription($input: SubscriptionCancellationInput!) {
    cancelSubscription(input: $input) {
      subscriptionId
      status
      cancellationDate
      endDate
    }
  }
  ```

  ```json Variables theme={null}
  {
    "input": {
      "subscriptionRefId": "sub-789",
      "subscriptionCancellationTime": "END_OF_BILLING_PERIOD"
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "cancelSubscription": {
        "subscriptionId": "sub-789",
        "status": "CANCELED",
        "cancellationDate": "2024-01-15T10:30:00Z",
        "endDate": "2024-02-15T00:00:00Z"
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="input" type="SubscriptionCancellationInput" required>
  Input for canceling a subscription

  <Expandable title="properties">
    <ParamField body="subscriptionRefId" type="String" required>
      The subscription reference ID to cancel
    </ParamField>

    <ParamField body="subscriptionCancellationTime" type="SubscriptionCancellationTime">
      When to cancel: `IMMEDIATE`, `END_OF_BILLING_PERIOD`, or `SPECIFIC_DATE`
    </ParamField>

    <ParamField body="endDate" type="DateTime">
      Specific cancellation date (required when `subscriptionCancellationTime` is `SPECIFIC_DATE`)
    </ParamField>

    <ParamField body="subscriptionCancellationAction" type="SubscriptionCancellationAction">
      Action on cancellation: `DEFAULT` or `REVOKE_ENTITLEMENTS`
    </ParamField>

    <ParamField body="prorate" type="Boolean">
      Whether to prorate credits on cancellation
    </ParamField>

    <ParamField body="environmentId" type="UUID">
      Environment ID
    </ParamField>
  </Expandable>
</ParamField>

## Cancellation Time Options

| Value                   | Behavior                                        |
| ----------------------- | ----------------------------------------------- |
| `IMMEDIATE`             | Cancel immediately                              |
| `END_OF_BILLING_PERIOD` | Cancel at the end of the current billing period |
| `SPECIFIC_DATE`         | Cancel on the date specified by `endDate`       |

## Cancellation Action Options

| Value                 | Behavior                                              |
| --------------------- | ----------------------------------------------------- |
| `DEFAULT`             | Default cancellation behavior                         |
| `REVOKE_ENTITLEMENTS` | Immediately revoke all entitlements upon cancellation |

## Return Type

Returns the canceled `CustomerSubscription` object with:

| Field              | Type               | Description                     |
| ------------------ | ------------------ | ------------------------------- |
| `subscriptionId`   | String             | Subscription ID                 |
| `status`           | SubscriptionStatus | New status (CANCELED)           |
| `cancellationDate` | DateTime           | When cancellation was requested |
| `endDate`          | DateTime           | When subscription ends          |

## Examples

### Immediate Cancellation

```json theme={null}
{
  "input": {
    "subscriptionRefId": "sub-789",
    "subscriptionCancellationTime": "IMMEDIATE",
    "subscriptionCancellationAction": "REVOKE_ENTITLEMENTS"
  }
}
```

### Cancel at Period End

```json theme={null}
{
  "input": {
    "subscriptionRefId": "sub-789",
    "subscriptionCancellationTime": "END_OF_BILLING_PERIOD"
  }
}
```

## Common Use Cases

<AccordionGroup>
  <Accordion title="Customer churn">
    Cancel when customer explicitly requests cancellation.
  </Accordion>

  <Accordion title="Payment failure">
    Cancel after failed payment recovery attempts.
  </Accordion>

  <Accordion title="Account deletion">
    Cancel as part of account deletion process.
  </Accordion>
</AccordionGroup>

## Related Operations

* [Update Subscription](/api-and-sdks/api-reference/mutations/update-subscription) - Modify instead of cancel
* [Archive Customer](/api-and-sdks/api-reference/mutations/archive-customer) - Archive customer and cancel all