Update Subscription

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

Plan changes are not supported by this mutation. To change a subscription’s plan, use provisionSubscription instead.

Mutation

Mutation

mutation UpdateSubscription($input: UpdateSubscriptionInput!) {
  updateOneSubscription(input: $input) {
    subscriptionId
    status
    plan {
      refId
      displayName
    }
    addons {
      addon {
        refId
        displayName
      }
      quantity
    }
    prices {
      billingPeriod
      price {
        amount
        currency
      }
    }
  }
}

{
  "input": {
    "subscriptionId": "sub-789",
    "addons": [
      { "addonId": "addon-seats", "quantity": 20 }
    ]
  }
}

{
  "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"
          }
        }
      ]
    }
  }
}

Parameters

input · UpdateSubscriptionInput · required

Input for updating a subscription

Show properties

subscriptionId · String · required

The subscription ID to update

billingPeriod · BillingPeriod

New billing period

addons · [SubscriptionAddonInput]

Updated addon configuration (replaces existing)

billableFeatures · [BillableFeatureInput]

Updated billable feature quantities

priceOverrides · [PriceOverrideInput]

Custom pricing overrides

cancellationDate · DateTime

Schedules, updates, or clears a future cancellation. Nullable — see the three-state PATCH semantics note below. Must be in the future and after the subscription’s startDate. Trial subscriptions are supported — see the trial behavior note below.

environmentId · UUID

Environment ID

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.

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.

Return Type

Returns the updated CustomerSubscription object.

Examples

Add Addon

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

Change Billing Period

{
  "input": {
    "subscriptionId": "sub-789",
    "billingPeriod": "ANNUAL"
  }
}

Schedule a Cancellation

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

{
  "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.

{
  "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 — it has different validation rules and supports flows like cancelling with open invoices.

Common Use Cases

Add seats

Increase addon quantity for seat-based subscriptions.

Switch to annual

Change from monthly to annual billing.

Schedule a future cancellation

Pass cancellationDate to queue a cancel on a known date; pass null to clear an existing schedule.

Related Operations

• Provision Subscription - Create or change a subscription’s plan
• Preview Subscription - Preview pricing impact
• Cancel Subscription - Cancel subscription
• Get Subscription - Get current subscription