Skip to main content
PATCH
/
apps
/
{app_id}
/
subscriptions_by_token
/
{token_type}
/
{token}
Update subscription By Token
curl --request PATCH \
  --url https://api.onesignal.com/apps/{app_id}/subscriptions_by_token/{token_type}/{token} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "subscription": {
    "enabled": true,
    "notification_types": 123,
    "session_time": 123,
    "session_count": 123,
    "app_version": "<string>",
    "device_model": "<string>",
    "device_os": "<string>",
    "test_type": 123,
    "sdk": "<string>",
    "rooted": true,
    "web_auth": "<string>",
    "web_p256": "<string>"
  }
}'
{}

​
Overview

Use this API to update an existing Subscription’s properties. This API can be useful if:
  • You only know the token and token_type and want to update metadata or status flags directly.
  • You are managing Subscription status outside of the OneSignal SDK. Like with a custom preference page or unsubscribe page.

​
How to use this API

To update a Subscription, you must know the token_type and the token. The token_type is the Subscription’s type (e.g., Email, SMS, iOSPush, AndroidPush, etc.). The token is the push token, email address, or phone number associated with the Subscription. Ensure the token is valid and correctly formatted for the chosen token_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.
You cannot update the token_type and token of a Subscription with this API. If the token_type is incorrect:
  1. Use Delete Subscription to remove the incorrect entry.
  2. Use Create Subscription by alias to recreate the subscription with the correct type.
If multiple Subscriptions are found for the token and token_type, an Http 400 error is returned with a list of subscription IDs that match the criteria.

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key. See Keys & IDs.

Path Parameters

​
app_id
string
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

​
token_type
enum<string>
required

The subscription channel type. Must match the format of the token.

Available options:
Email,
SMS,
iOSPush,
AndroidPush,
HuaweiPush,
FireOSPush,
WindowsPush,
macOSPush,
ChromeExtensionPush,
ChromePush,
FirefoxPush,
SafariPush
​
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. 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.

Body

application/json
​
subscription
object

The subscription's properties.

Response

202

The Subscription update request has been accepted successfully. This process is asynchronous and may take a few seconds to complete.