Subscriptions API
Devices. Public or secret key, scope subscriptions:write. These are the calls the SDKs make; you only need them for custom clients or imports.
POST /v1/subscriptions — register (upsert)
Rate-limited per client IP. Upserts by (appId, token) for mobile or (appId, endpoint) for web, so calling it on every launch is correct.
Mobile body
{
"platform": "ios", // or "android"
"token": "<APNs device token / FCM registration token>",
"externalId": "user_123", // optional → login at subscribe time
"tags": { "plan": "premium" }, // optional, merged into the user
"language": "tr", "timezone": "Europe/Istanbul", "country": "TR",
"appVersion": "3.4.1", "sdkVersion": "0.1.0", "osVersion": "17.5", "deviceModel": "iPhone 15 Pro"
}
Web body
{
"platform": "web",
"endpoint": "https://fcm.googleapis.com/fcm/send/…",
"keys": { "p256dh": "…", "auth": "…" },
"browser": "chrome",
"standalone": true, // installed as a PWA
"externalId": "user_123", "tags": {}, "language": "en", "timezone": "Europe/London"
}
Response 200
{ "id": "66f1…", "platform": "ios", "userId": "66f2…" }
Re-subscribing revives an opted-out or invalidated row. If externalId is given the identity rules run exactly as for login.
PATCH /v1/subscriptions/:id — device fields
{ "optedIn": false, "appVersion": "3.5.0", "osVersion": "18.0", "deviceModel": "…", "rooted": false, "location": { "lat": 41.0, "lon": 28.9 } }
Device-level only; location: null clears a position the app no longer has permission for. Anything about the person goes through /user below. 200 { "id", "optedIn" }.
POST /v1/subscriptions/:id/session — the app came to the foreground
{ "appVersion": "3.5.0", "osVersion": "18.0", "usageDuration": 90, "location": { "lat": 41.0, "lon": 28.9 } }
Body optional. usageDuration is foreground seconds since the previous ping — a delta, added to the device's total (an import may have seeded it); location is the last known position when the app holds permission. Refreshes lastActiveAt and, if the previous session started 30 minutes or more ago, increments sessionCount and sets lastSessionAt — the OneSignal session rule, applied on the server so the SDKs can ping on every foreground without counting twice. POST /v1/subscriptions (the upsert every SDK runs at launch) applies the same rule, so an app on an older SDK still gets counts, just coarser ones.
200 { "id", "sessionCount", "lastSessionAt" }. The counters are segment fields: sessionCount gte 5, lastSessionAt lt -30d.
POST /v1/subscriptions/:id/outcomes — a conversion
{ "name": "purchase", "value": 9.99, "msgId": "eyJ…" }
name matches ^[a-z0-9_-]{1,64}$; value (optional, default 0) is summed. msgId is the notification the user opened shortly before — the SDKs attach it within their attribution window (24 hours by default). When it verifies and was sent to this device or another device of the same user, the outcome is credited to that campaign (stats.outcomes.<name>.count / .value, shown on the campaign report); otherwise it is stored unattributed. Public key allowed, rate-limited per device.
201 { "attribution": "direct" | "unattributed", "campaignId": string | null }
POST /v1/subscriptions/:id/login
{ "externalId": "user_123" }
200 { "userId": "…", "externalId": "user_123" }. Renames the anonymous user or moves the device — see Identity.
POST /v1/subscriptions/:id/logout
No body. 200 { "userId": "<new anonymous user>" }.
PATCH /v1/subscriptions/:id/user — owning user's properties
Also available as POST (Android's HttpURLConnection cannot send PATCH). Same body as PATCH /v1/users/:id:
{ "tags": { "plan": "platinum", "streak": null }, "language": "tr", "timezone": "Europe/Istanbul", "country": "TR" }
Tags merge; null removes a key. The write reaches every device of the user. 200 { "userId", "tags" }.
DELETE /v1/subscriptions/:id
204. Removes the device; an anonymous owner with no devices left is removed too.
POST /v1/subscriptions/rotate — web endpoint changed
Sent by the service worker on pushsubscriptionchange:
{ "old": "https://…/old-endpoint", "new": { "endpoint": "https://…/new", "keys": { "p256dh": "…", "auth": "…" } } }
200 { "id" } — the row is updated in place, the subscriber is not lost. 404 if the old endpoint is unknown.
Errors
404 not_found for an unknown or foreign id (an id from another app is indistinguishable from a non-existent one), 422 invalid_body with field details, 429 rate_limited.