PATCH
/
apps
/
{app_id}
/
subscriptions
/
{subscription_id}
Update subscription
curl --request PATCH \
  --url https://api.onesignal.com/apps/{app_id}/subscriptions/{subscription_id} \
  --header 'Content-Type: application/json' \
  --data '{
  "subscription": {
    "type": "Email",
    "token": "<string>",
    "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 endpoint is primarily used by the OneSignal SDK to manage subscription state. Most external use cases are better served by the Update User API, which allows for updating user-level data, including associated subscriptions. However, this API can be useful if:
  • You are managing Subscriptions outside of the OneSignal SDK.
  • You need to programmatically disable (enabled: false) a Subscription (e.g., due to a manual opt-out).
  • You know the subscription_id and want to update metadata or status flags directly.
For email opt-outs, it’s recommended to use the Unsubscribe Email (with token) API instead. This avoids the need to store or manage the subscription_id.

​
How to use this API

Required: subscription_id To update a subscription, you must know the subscription_id. This is a UUID generated by OneSignal and is immutable.
  • You can retrieve a subscription ID by querying the User object, which lists all associated subscriptions.
  • See the Subscriptions guide for an explanation of how subscription IDs are generated and used.

Path Parameters

​
app_id
string
required

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

​
subscription_id
string
required

The unique Subscription ID in UUID v4 format generated by OneSignal. See Subscriptions.

Body

application/json

Response

200
application/json

200

The Subscription updated successfully. This process is asynchronous and may take a few seconds to complete.