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

# Update Subscription

Modifies an existing subscription, allowing addon updates, billing period changes, and more.

<Note>
  Plan changes are not supported by this mutation. To change a subscription's plan, use [provisionSubscription](/api-and-sdks/api-reference/mutations/provision-subscription) instead.
</Note>

## Mutation

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation UpdateSubscription($input: UpdateSubscriptionInput!) {
    updateOneSubscription(input: $input) {
      subscriptionId
      status
      plan {
        refId
        displayName
      }
      addons {
        addon {
          refId
          displayName
        }
        quantity
      }
      prices {
        billingPeriod
        price {
          amount
          currency
        }
      }
    }
  }
  ```

  ```json Variables theme={null}
  {
    "input": {
      "subscriptionId": "sub-789",
      "addons": [
        { "addonId": "addon-seats", "quantity": 20 }
      ]
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "updateOneSubscription": {
        "subscriptionId": "sub-789",
        "status": "ACTIVE",
        "plan": {
          "refId": "plan-pro",
          "displayName": "Pro Plan"
        },
        "addons": [
          {
            "addon": {
              "refId": "addon-seats",
              "displayName": "Extra Seats"
            },
            "quantity": 20
          }
        ],
        "prices": [
          {
            "billingPeriod": "MONTHLY",
            "price": {
              "amount": 99,
              "currency": "USD"
            }
          }
        ]
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="input" type="UpdateSubscriptionInput" required>
  Input for updating a subscription

  <Expandable title="properties">
    <ParamField body="subscriptionId" type="String" required>
      The subscription ID to update
    </ParamField>

    <ParamField body="billingPeriod" type="BillingPeriod">
      New billing period
    </ParamField>

    <ParamField body="addons" type="[SubscriptionAddonInput]">
      Updated addon configuration (replaces existing)
    </ParamField>

    <ParamField body="billableFeatures" type="[BillableFeatureInput]">
      Updated billable feature quantities
    </ParamField>

    <ParamField body="priceOverrides" type="[PriceOverrideInput]">
      Custom pricing overrides
    </ParamField>

    <ParamField body="cancellationDate" type="DateTime">
      Schedules, updates, or clears a future cancellation. Nullable — see the [three-state PATCH semantics](#cancellationdate-three-state-semantics) note below. Must be in the future and after the subscription's `startDate`. Trial subscriptions are supported — see the [trial behavior](#trial-behavior) note below.
    </ParamField>

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

### `cancellationDate` three-state semantics

`cancellationDate` is both **optional** and **nullable**. The three input states behave differently — pay attention if you marshal updates through a generic JSON-merge layer:

| Input state                                | Behavior                                                                 |
| ------------------------------------------ | ------------------------------------------------------------------------ |
| Field omitted from input                   | No change. Existing scheduled cancellation (if any) is preserved.        |
| `cancellationDate: null`                   | Clears any scheduled cancellation. Subscription continues / auto-renews. |
| `cancellationDate: "2024-12-31T00:00:00Z"` | Sets or updates the scheduled cancellation to the supplied date.         |

<Warning>
  Don't conflate **omitted** with **`null`**. Serializers that drop `null` values will silently turn a "clear the schedule" request into a no-op; serializers that emit `null` for unset fields will silently clear a customer's existing scheduled cancellation. Make sure your client passes the field exactly as intended.
</Warning>

## Return Type

Returns the updated `CustomerSubscription` object.

## Examples

### Add Addon

```json theme={null}
{
  "input": {
    "subscriptionId": "sub-789",
    "addons": [
      { "addonId": "addon-seats", "quantity": 5 },
      { "addonId": "addon-storage", "quantity": 1 }
    ]
  }
}
```

### Change Billing Period

```json theme={null}
{
  "input": {
    "subscriptionId": "sub-789",
    "billingPeriod": "ANNUAL"
  }
}
```

### Schedule a Cancellation

Queue a cancellation on an existing subscription. The subscription remains active until the supplied date.

```json theme={null}
{
  "input": {
    "subscriptionId": "sub-789",
    "cancellationDate": "2024-12-31T00:00:00Z"
  }
}
```

### Clear a Scheduled Cancellation

Remove a previously scheduled cancellation. The subscription continues and will auto-renew.

```json theme={null}
{
  "input": {
    "subscriptionId": "sub-789",
    "cancellationDate": null
  }
}
```

#### Trial behavior

Trial subscriptions accept `cancellationDate`:

* **Setting a date** (`cancellationDate: "<date>"`) aligns `trialEndDate` to the supplied date — the trial ends and the subscription cancels on the same date.
* **Clearing the schedule** (`cancellationDate: null`) preserves the subscription's original `trialEndDate`.

For immediate cancellation (rather than scheduled), use [Cancel Subscription](/api-and-sdks/api-reference/mutations/cancel-subscription) — it has different validation rules and supports flows like cancelling with open invoices.

## Common Use Cases

<AccordionGroup>
  <Accordion title="Add seats">
    Increase addon quantity for seat-based subscriptions.
  </Accordion>

  <Accordion title="Switch to annual">
    Change from monthly to annual billing.
  </Accordion>

  <Accordion title="Schedule a future cancellation">
    Pass `cancellationDate` to queue a cancel on a known date; pass `null` to clear an existing schedule.
  </Accordion>
</AccordionGroup>

## Related Operations

* [Provision Subscription](/api-and-sdks/api-reference/mutations/provision-subscription) - Create or change a subscription's plan
* [Preview Subscription](/api-and-sdks/api-reference/mutations/preview-subscription) - Preview pricing impact
* [Cancel Subscription](/api-and-sdks/api-reference/mutations/cancel-subscription) - Cancel subscription
* [Get Subscription](/api-and-sdks/api-reference/queries/get-subscription) - Get current subscription