Skip to main content
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 UpdateSubscription($input: UpdateSubscriptionInput!) {
  updateOneSubscription(input: $input) {
    subscriptionId
    status
    plan {
      refId
      displayName
    }
    addons {
      addon {
        refId
        displayName
      }
      quantity
    }
    prices {
      billingPeriod
      price {
        amount
        currency
      }
    }
  }
}

​
Parameters

​
input
UpdateSubscriptionInput
required
Input for updating a subscription

​
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 stateBehavior
Field omitted from inputNo change. Existing scheduled cancellation (if any) is preserved.
cancellationDate: nullClears 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

Increase addon quantity for seat-based subscriptions.
Change from monthly to annual billing.
Pass cancellationDate to queue a cancel on a known date; pass null to clear an existing schedule.