---
title: "Update subscription"
method: PATCH
path: "/subscriptions/{id}"
tags: ["Subscriptions"]
---

# Update subscription

`PATCH /subscriptions/{id}`

## Request

- Base URL: `https://api.smokeball.com`
- URL: `https://api.smokeball.com/subscriptions/{id}`
- Auth: API key in header `x-api-key` and API key in header `Authorization`

Updates a subscriptions tiers, add-ons, or interval.

Important considerations:
* Updates cannot be made to canceled subscriptions
* Billing will be prorated for the remaining period
* Existing add-ons may need to be re-validated
* Some features may be disabled if not available in new tier or add-ons

## Path parameters

- `id` string, required

## Request body

- UpdateSubscriptionRequest
  - `tierId` string, uuid, nullable: Optional tier id to subscribe to. An error is thrown if the supplied or existing add-ons are not valid for the supplied tier id.
  - `archieTierId` string, uuid, nullable: Optional Archie tier id to subscribe to. Omit or supply null to preserve the current Archie tier. Use DELETE /subscriptions/{id}/archie-tier to remove it.
  - `addOnIds` string[], nullable: Optional add-on ids to subscribe to. An error is thrown if the supplied or existing add-ons are not valid for the existing or supplied tier id.
  - `interval` string, nullable: Optional billing interval/pricing option to use when setting subscription tier. If an interval is not supplied then the default interval option will be used. If an interval is supplied but a tier is not supplied, the existing tier is used and the interval is changed.
  - `promotionId` string, uuid, nullable: Optional promotion id to apply with the subscription change. The promotion is validated against the requested tier, Archie tier, and add-ons.
  - `reason` string, nullable: Optional reason for changing the subscription tier.

## Response `202`

When request is accepted. Returns a 'Link' object.

- Link
  - `id` string, nullable
  - `href` string, nullable
  - `relation` string, nullable
  - `method` string, nullable

## Other responses

- `400`: When an unsupported request is made.
- `404`: When subscription with specified id does not exist.
- `500`: When an error occurs while updating the subscription.

## Changes

- **2026-10-28** `2fe552c5d11d`: 3 info
  - added the new optional request property `allOf[#/components/schemas/UpdateSubscriptionRequest]/promotionId` (media type: application/json-patch+json)
  - added the new optional request property `allOf[#/components/schemas/UpdateSubscriptionRequest]/promotionId` (media type: application/json)
  - added the new optional request property `allOf[#/components/schemas/UpdateSubscriptionRequest]/promotionId` (media type: application/*+json)
- **2026-09-12** `30062b3c3dd5`: 3 info
  - added the new optional request property `allOf[#/components/schemas/UpdateSubscriptionRequest]/archieTierId` (media type: application/json-patch+json)
  - added the new optional request property `allOf[#/components/schemas/UpdateSubscriptionRequest]/archieTierId` (media type: application/json)
  - added the new optional request property `allOf[#/components/schemas/UpdateSubscriptionRequest]/archieTierId` (media type: application/*+json)

[Operation history](https://skmtc.dev/smokeball/apis/smokeball-api/changes/subscriptions/:id/patch.md)

---

[API](https://skmtc.dev/smokeball/apis/smokeball-api.md) - [All operations](https://skmtc.dev/smokeball/apis/smokeball-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smokeball/apis/smokeball-api/revisions/6e350cf667d4?raw)