Server REST API Reference
Log InSign Up

Update subscription

patch https://api.onesignal.com/apps//subscriptions/

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

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.


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 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

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, then use in conjunction with the notification_types property.


notification_types

Type number

Description

Indicates the reason for the Subscription's status details. Values are updated automatically when events are detected.

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.

This is because 1 denotes an active subscription and -31 denotes a subscription that has been disabled via the 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
  • -4, -8, -11, -12 = Android Google Play Services Library Error
  • -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
  • -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.
    • Permission was revoked.
  • -23, -24 = Web Service Worker Error.
  • -31 = Disabled via 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.


Language