Update a subscription's properties.
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
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
Type string
Platforms All
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
token
Type string
Platforms All
Description
The push token, email address, or SMS phone number associated with the subscription. Ensure the token
is valid and correctly formatted for the chosen subscription type
.
Phone numbers must be in E.164 format to be valid.
enabled
enabled
Type bool
Platforms All
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, then use in conjunction with the notification_types
property.
notification_types
notification_types
Type number
Description
Indicates the reason for the subscription status change. Use in conjunction with the enabled
property when changing a subscription's status.
If changing the enabled
status to true
, set notification_types
to 1
.
If changing the enabled
status to false
, set notification_types
to -99
.
session_time
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
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
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
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
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
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
sdk
Type string
Description
Only available to OneSignal SDKs. Indicates the OneSignal SDK version.
rooted
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
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
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.