---
title: "Update subscription"
method: PATCH
path: "/apps/{app_id}/subscriptions/{subscription_id}"
---

# Update subscription

`PATCH /apps/{app_id}/subscriptions/{subscription_id}`

Update properties on an existing OneSignal subscription using its subscription_id. Commonly used to enable or disable a subscription when managing outside of the OneSignal SDK.

## Path parameters

- `app_id` string, required
- `subscription_id` string, required

## Request body

- object
  - `subscription` object — The subscription's properties.
    - `type` 'Email' | 'SMS' | 'iOSPush' | 'AndroidPush' | 'HuaweiPush' | 'FireOSPush' | 'WindowsPush' | 'macOSPush' | 'ChromeExtensionPush' | 'ChromePush' | 'SafariLegacyPush' | 'FirefoxPush' | 'SafariPush', required — The subscription channel type. Must match the format of the token.
    - `token` string, required — The push token, email address, or phone number associated with the subscription. Ensure the `token` is valid and correctly formatted for the chosen subscription `type`. Email format: Should be a valid email address that you confirmed can receive emails. SMS format: Phone number must be in [E.164 format](https://en.wikipedia.org/wiki/E.164). iOSPush APNS token format: 64 characters, hexadecimal characters only (0-9,a-f). AndroidPush FCM token format: Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.
    - `enabled` boolean — Indicates if the Subscription should be subscribed to the message channel. Defaults to `true` if omitted. Set to `false` to mark as unsubscribed.
    - `notification_types` integer — Indicates the reason for the subscription status. Values are updated automatically as events are detected by our frontend SDKs but you should set this manually when updating via our REST API. `1` is subscribed and `-31` is reserved for unsubscribed via the API. See [Subscriptions](/docs/subscriptions#notification-types).
    - `session_time` integer — The total amount of time the user has had the app open in seconds.
    - `session_count` integer — The total amount of times the user has opened the app.
    - `app_version` string — The version of your mobile app as detected by our frontend SDKs or a value you set via our API. Our SDK sets this based: Android - Android Studio `versionCode` in your App `build.gradle`. iOS: Xcode App Version.
    - `device_model` string — The model of the user's device (e.g., iPhone 16).
    - `device_os` string — The device or browser's system version.
    - `test_type` integer — Specifies the [APS environment entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) used for generating the iOS push token. Omit, set to `null` or `0` if the token was generated in a Production environment (App Store & Test Flight builds). Set to `1` for Development environment, `2` if it was generated in an Ad-Hoc environment. This ensures OneSignal routes notifications correctly based on the token’s source environment.
    - `sdk` string — Set by our frontend SDK. Do not use this field. Indicates the OneSignal SDK version.
    - `web_auth` string — The web auth token set by our web SDK. Do not use this field. See [Migrating to OneSignal from another service](/docs/migrating-to-onesignal).
    - `web_p256` string — The web 256 key set by our web SDK. Do not use this field. See [Migrating to OneSignal from another service](/docs/migrating-to-onesignal).

## Response `200`

200

- object — The Subscription updated successfully. This process is asynchronous and may take a few seconds to complete.

## Other responses

- `400` — 400
- `429` — Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.
- `503` — Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.

---

[API](https://skmtc.net/onesignal/apis/api-onesignal-com.md) · [All operations](https://skmtc.net/onesignal/apis/api-onesignal-com/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onesignal/api-onesignal-com/versions/0fc223f7e338/schema)