Overview

Use this API to update an existing subscription's properties.

This API is used mostly by our SDK to update subscription properties. There are few reasons why you would use this API and you are likely looking for the Update user API instead.

It is most commonly used to update the enabled status on a subscription if tracking it outside of our SDK. However, for email, you likely want to use the Unsubscribe email (with token) API instead so you don't need to store the subscription_id.

How to use this API

You must know the subscription_id of the subscription in which you want to update. Subscription IDs are UUIDs generated by OneSignal and cannot change. See Subscriptions for details.

You cannot update the subscription's type. If you made a mistake with a subscription's type, use Delete subscription API first to delete the wrong subscription, then the Create subscription (by alias) API to create a new subscription for that user.

Body parameters

`subscription`

Type object

Description

Represents a user's intent to receive messages through a given channel. See Subscriptions for details.

Use this subscription object to create or update one subscription associated with a user.

token
enabled
notification_types
session_time
session_count
app_version
device_model
device_os
test_type
sdk
rooted
web_auth
web_p256

Subscription property definitions (click to expand)

`type`

Type string

Description

Enum of SubscriptionType, representing the type of subscription (e.g., push notification, email, SMS). Choose the subscription type based on the channel in which you have the matching token. See Subscriptions for details.

Valid values include:

Email
SMS
iOSPush
AndroidPush
HuaweiPush
FireOSPush
WindowsPush
macOSPush
ChromeExtensionPush
ChromePush
FirefoxPush
SafariPush

`token`

Type string

Description

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.

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.

{
  "subscriptions": [
    {
      "type": "Email",
      "token": "[email protected]"
    },
    {
      "type": "SMS",
      "token": "+15551234567"
    },
    {
      "type": "iOSPush",
      "token": "7abcd49d0affb7426a8f1202420e8f4e2fc4df58e49501adc383f3bd66df8636"
    },
    {
      "type": "AndroidPush",
      "token": "dQGm89TZQXiTvLsRIj_GBo:APA91bpgqFgqkP2qYvV1uW2kdK5Z3TjgCXB_1jkL6VJrgH3hoYn16MvFY19tzDE4OuSgKjYC7itbFpSJYHBfKLWt-xZYBpgCVhYn9K5neV_9-Zj7s9mOSjRUJ2IwEwVSYhR-j5ICF9WB"
    }
  ]
}

`enabled`

Type bool

Description

Indicates if the subscription is currently active. Defaults to true if omitted. Set this to false if the user has unsubscribed.

If you are changing the subscriptions status via our REST API, then use in conjunction with the notification_types property to indicate how and why you changed it.

`notification_types`

Type number

Description

Indicates the reason for the Subscription's status details. Values are updated automatically when events are detected by our SDK but you should set them manually when updating via our REST API.

When creating Subscriptions, we recommend setting this to 1 if the Subscription's token is able to receive messages and the user has given permission to receive messages on this channel. Otherwise, you should omit the Subscription and just add the User properties.

Can be used in conjunction with the enabled property.

📘
Changing Subscription Statuses
When changing a subscription status, we recommend settingnotification_types to 1when setting enabled to trueand setting notification_types to -31when setting enabled to false.
1 denotes a subscribed subscription and -31 denotes a subscription that has been unsubscribed via the REST API. For a full list of possible notification_types values and their definitions, please see below.

Notification types definitions (click to expand)

1 or positive number = Subscribed

The Subscription can receive messages on this channel.

Can be used with enabled property if you are enabling messages on behalf of the user. For push Subscriptions, a valid token must still be set to receive push notifications. See our SDK setup docs for details.

0, -99 = Never Subscribed

The Subscription has not subscribed to the channel yet.

-2 = Unsubscribed

The Subscription cannot receive messages on this channel.

Can be used with enabled property set to false if you are turning off messages on behalf of the user. Recommended value when turning off message permissions.

Automatically set when the user unsubscribes.

-3, -5 = Android Support Library Error

Add or update your app's Android Support Library.

-4, -8, -11, -12 = Android Google Play Services Library Error

Check the logcat. See Getting a Debug Log.

Upgrade your Google Play Services Library in your app and check the app's logcat for Google Play Services errors. See Getting a Debug Log.

-6 = Android Invalid Google Project Number

The FCMv1 Sender ID doesn't match the original in which this token belongs. Check the app's logcat. See Getting a Debug Log.

-7, -9 = Android Outdated Google Play Services App

Update or enable the Google Play Services app on the device.

-10 = Not Subscribed.

Push Subscription uninstalled app or unsubscribed in device settings.

Web push blocked notifications, cleared all data and workers.

-13 = iOS missing_push_capability.

Review the SDK setup docs to make sure all steps are implemented. See Channel setup.

-14, -16, -17 = iOS APNS Errors

The device is having an issue connecting to APNS. Check the Troubleshooting iOS guide and Getting a Debug Log.

-15 = iOS Simulator Error

iOS Simulator required iOS 16.4+ Use a different simulator or device.

-18 = Never Prompted

The Subscription was never prompted to subscribe. This only tracks the required permission prompt and does not include in-app messages.

-19 = Prompted But Never Answered

The Subscription was prompted but didn't provide an answer.

-20, -21 = temp_web_record. Web, pushsubscriptionchange permission revoked

-22 = Manually Unsubscribed via dashboard.

Permission was revoked.

-23, -24 = Web Service Worker Error.

See Web SDK troubleshooting.

-31 = Disabled via REST API.

-98 = SMS Subscription awaiting double opt-in.

`session_time`

Type number

Description

The total amount of time the user has had the app open in seconds. Use this data to track user engagement and app usage patterns.

`session_count`

Type number

Description

The number of times the user has opened the app. This metric can be used to identify active users and those who should be re-engaged.

`app_version`

Type string

Description

The version of your app that the user is currently using. This information is useful for troubleshooting, filtering users based on app versions, and ensuring compatibility.

`device_model`

Type string

Description

The model of the user's device (e.g., iPhone 14). Use this data to optimize app performance and ensure compatibility with different device models.

`device_os`

Type string

Description

The device's operating system version. This data is beneficial for providing operating system specific support and updates.

`test_type`

Type number

Platform iOS mobile push

Description

Indicates which APS environment entitlement to use for your iOS app build.

If the iOS push token was generated in a Production environment, you can omit the test_type property (null) or set to 0.
If the iOS push token was generated in a Development environment, set test_type to 1 indicating "Development".
If the iOS push token was generated in an Ad-Hoc environment, set test_type to 2 indicating "Ad-Hoc".

`sdk`

Type string

Description

Only available to OneSignal SDKs. Indicates the OneSignal SDK version.

`rooted`

Type bool

Platform Android mobile push

Description

Only available to OneSignal SDKs. Indicates if the Android device is rooted or jail-broken.

`web_auth`

Type string

Platform Web push

Description

Only available to OneSignal SDKs. The web_auth key for web push. You should not import web push tokens; see Importing Web Push Subscriptions for details.

`web_p256`

Type string

Platform Web push

Description

Only available to OneSignal SDKs. You should not import web push tokens; see Importing Web Push Subscriptions for details.

Update subscription

Overview

How to use this API

Body parameters

`subscription`

`type`

`token`

`enabled`

`notification_types`

📘
Changing Subscription Statuses

`session_time`

`session_count`

`app_version`

`device_model`

`device_os`

`test_type`

`sdk`

`rooted`

`web_auth`

`web_p256`

Overview

How to use this API

Body parameters

subscription

type

token

enabled

notification_types

📘Changing Subscription Statuses

session_time

session_count

app_version

device_model

device_os

test_type

sdk

rooted

web_auth

web_p256

`subscription`

`type`

`token`

`enabled`

`notification_types`

📘
Changing Subscription Statuses

`session_time`

`session_count`

`app_version`

`device_model`

`device_os`

`test_type`

`sdk`

`rooted`

`web_auth`

`web_p256`