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

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

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

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

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

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