Push notifications API overview
Used byCustom website, JavaScript SDK, Mobile SDKs, iOS (Swift), Flutter, React Native, Android (Kotlin)
There is no public API to create or send a push notification. Notifications are created in the admin under Marketing Channels › Push Notifications and sent by campaigns and workflows. The public API only registers the devices that can receive them:
| Endpoint | Purpose |
|---|---|
POST /appPush/tokens |
Register a mobile app push token (Android FCM token, or iOS APNs token) |
POST /pushSubscriptions/{accessToken} |
Register a browser’s Web Push subscription. The JS SDK calls it for you |
POST /push/{accessToken} |
The regular SDK call. Its response carries the VAPID public key the browser subscribes with |
Base URL: https://releva.ai/api/v0. For what happens after registration, read How push notifications work.
When to use it
Section titled “When to use it”- Web push with the Releva JS SDK: you do not call anything. Host the service worker, pass
serviceWorkerUrltoReleva.push, and the SDK registers the subscription. See Web push setup. - Mobile apps: the Releva React Native and Swift SDKs call
POST /appPush/tokensfor you (client.registerPushToken(...)). Call it yourself only from a custom app stack. - Your own web push opt-in (own service worker and
pushManager.subscribe): callPOST /pushSubscriptions/{accessToken}with the subscription and the VAPID key from theReleva.pushresponse.
Authentication
Section titled “Authentication”Both registration endpoints use the shop’s access token, the public key your website and apps already use, not the secret key. Find both under Settings › Shop & Integration; see Find your API keys.
authorization: Bearer $RELEVA_ACCESS_TOKENFor /pushSubscriptions the token can instead be the last path segment, which is what the JS SDK does to avoid a CORS pre-flight. If both are sent, the header wins and the path segment is not checked.
Authentication failures answer 400, not 401:
| Problem | Message |
|---|---|
| No header and no path token | Authorization header is missing, and accessToken url parameters is also missing. At least one of them is required. |
Header is not Bearer <token> |
Authorization header is malformed. It should look like `Bearer <string>`. |
| Token is not a UUID | The access token you provided is invalid. |
| No shop has this token (including the secret key by mistake) | Domain with the provided access token cannot be found. |
A shop that has been switched off answers 402 with Domain is disabled. Please reach out to support@releva.ai to enable it.
Request format
Section titled “Request format”- HTTPS only.
- Send JSON with
content-type: application/json. With no body or another content type you get400 {"message":"The '' field is required."}. /pushSubscriptionsalso acceptsapplication/x-www-form-urlencodedwith one field,formPayload, holdingbase64(encodeURIComponent(JSON)). That is the SDK’s format; without the field:400 {"message":"formPayload is missing from request body"}.- Bodies are limited to 800 KB (JSON).
- Unknown fields are ignored, not rejected.
Responses
Section titled “Responses”Both endpoints answer 202 Accepted with {}. Storage is asynchronous; the device is targetable a few seconds later. Errors have one shape, { "message": "..." }; several validation errors are joined with a space.
| Status | When |
|---|---|
202 |
Accepted and queued |
400 |
Authentication failed, validation failed, the body could not be parsed, or the APNs token could not be imported |
402 |
The shop is disabled |
413 |
Body too large |
500 |
Unexpected error, {"message":"An internal error occurred."}. Retry later |
Limits
Section titled “Limits”- No rate limit on these endpoints.
- Every call writes a Push Notification Subscribe event on the profile, even for the same device. A workflow triggered on that event fires on every call, so register once per token change, not on every app start.
- There is no endpoint to remove a token or subscription. Releva deletes it when the push service rejects it at send time.
Web push setup
Section titled “Web push setup”-
Copy Releva’s service worker file (
service-worker.jsfrom the Releva JS SDK) to your site and serve it from the same origin, for examplehttps://demo-store.example.com/releva-sw.js. It shows a notification only for payloads withsource: "releva"and opens the notification’s link on click. -
Pass its URL to the SDK:
Releva.push(accessToken, context, { serviceWorkerUrl: '/releva-sw.js' }); -
On each response the SDK reads
push.vapidPublicKey. If the browser supports service workers and notifications and the permission is not denied, it asks for permission, registers the worker and subscribes withuserVisibleOnly: true. An existing subscription made with another key is replaced. -
The SDK posts the subscription to
/pushSubscriptions/{accessToken}with the device id and the profile from the context.
Without serviceWorkerUrl the SDK never asks for permission and no browser can be reached.
Endpoints
Section titled “Endpoints”Register a mobile app push token
Section titled “Register a mobile app push token”POST /api/v0/appPush/tokens
| Field | Type | Required | Notes |
|---|---|---|---|
profileId |
string | yes | Your customer id for the profile. null is rejected. If the profile does not exist yet, a placeholder profile is created |
deviceId |
string | yes | Stable id of the app install. One token per profile and device |
deviceType |
android, ios, huawei, other |
no | Stored as the token’s platform. Only android and ios tokens receive pushes: always send it |
pushToken |
string | yes | FCM registration token, or a raw APNs device token with tokenType: "apns" |
tokenType |
fcm (default), apns |
no | apns: Releva exchanges the APNs token for an FCM token through the shop’s iOS Firebase project and stores the device as ios |
bundleId |
string | with apns |
The app’s iOS bundle identifier |
notificationStyle |
data (default), notification |
no | notification: Android draws the push natively from an FCM notification block (used by the Expo adapter). data: the SDK draws it |
curl -X POST 'https://releva.ai/api/v0/appPush/tokens' \ -H "authorization: Bearer $RELEVA_ACCESS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "profileId": "DEMO-CUSTOMER-1001", "deviceId": "demo-device-android-0001", "deviceType": "android", "pushToken": "<FCM registration token>" }'iOS with a raw APNs token (Expo):
curl -X POST 'https://releva.ai/api/v0/appPush/tokens' \ -H "authorization: Bearer $RELEVA_ACCESS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "profileId": "DEMO-CUSTOMER-1001", "deviceId": "demo-device-ios-0001", "deviceType": "ios", "pushToken": "<64-character APNs device token>", "tokenType": "apns", "bundleId": "com.example.shop" }'Response: 202 {}.
| Cause | Message |
|---|---|
Empty body {} |
The 'profileId' field is required. The 'deviceId' field is required. The 'pushToken' field is required. |
profileId: null (SDK called before setProfileId) |
The 'profileId' field is required. |
deviceType: "web" |
The 'deviceType' field does not match any of the allowed values. |
tokenType: "hms" |
The 'tokenType' field does not match any of the allowed values. |
notificationStyle: "banner" |
The 'notificationStyle' field does not match any of the allowed values. |
64-hex APNs token without tokenType: "apns" |
pushToken looks like a raw APNs device token. Send tokenType "apns" with bundleId so it can be exchanged for an FCM registration token. |
apns without bundleId |
bundleId is required when tokenType is apns. |
apns on a shop without an iOS Firebase account |
No iOS Firebase account is configured for this domain. |
| Firebase rejected the APNs token | APNs token could not be imported into FCM. Status: <STATUS>. where STATUS is INVALID_ARGUMENT, UNAUTHENTICATED, PERMISSION_DENIED, INTERNAL, TOO_MANY_REGISTRATIONS or UNKNOWN. A development build has a sandbox token: set iOS APNs environment to Sandbox for it |
Register a browser push subscription
Section titled “Register a browser push subscription”POST /api/v0/pushSubscriptions/{accessToken}
Body: context and subscription.
| Field | Type | Required | Notes |
|---|---|---|---|
context.deviceId |
string | no | The browser device id (the SDK’s rlv_p cookie). The subscription is stored per device |
context.profile.id |
string | no | Your customer id; links the device to that profile |
context.profile.email |
no | Upserted onto the profile | |
context.profile.phoneNumber |
string | no | International format with + and country code |
context.group |
0 to 9999 | no | Control-group bucket; default 9999 |
subscription |
object | yes | The browser’s PushSubscription.toJSON() |
subscription.endpoint |
URL | yes | |
subscription.expirationTime |
string or null |
no | A number is rejected, see errors |
subscription.keys.p256dh, subscription.keys.auth |
string | yes |
curl -X POST "https://releva.ai/api/v0/pushSubscriptions/$RELEVA_ACCESS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "context": { "deviceId": "demo-browser-device-0001", "profile": { "id": "DEMO-CUSTOMER-1001", "email": "maria@example.com" } }, "subscription": { "endpoint": "https://push.example.com/send/demo-subscription-0001", "expirationTime": null, "keys": { "p256dh": "<p256dh key>", "auth": "<auth secret>" } } }'Response: 202 {}.
| Cause | Message |
|---|---|
No context |
context is missing from request body |
No subscription |
The 'subscription' field is required. |
endpoint not a URL |
The 'subscription.endpoint' field must be a valid URL. |
| Missing key | The 'subscription.keys.auth' field is required. |
expirationTime sent as a number |
The 'subscription.expirationTime' field must be a string. Send null or a string |
| Bad e-mail | The 'context.profile.email' field must be a valid e-mail. |
phoneNumber: "abc" |
context.profile.phoneNumber must be a valid telephone number starting with + and international code, e.g. +1. Got abc instead. |
group: 10000 |
The 'context.group' field must be less than or equal to 9999. |
| Path token not a UUID | The access token you provided is invalid. |
| No path segment at all | 404 (route not found) |
Where the VAPID key comes from
Section titled “Where the VAPID key comes from”POST /api/v0/push/{accessToken} is the SDK’s regular call, documented in the Events API overview. Every 200 response includes:
{ "push": { "vapidPublicKey": "<base64url VAPID public key>" } }Use it as applicationServerKey when you subscribe a browser yourself. The key is the same for every shop on a Releva environment.
What a delivered push contains
Section titled “What a delivered push contains”For reference when you build your own service worker or app handler. All text and URL fields are rendered per profile (merge tags, trigger event, product for recommender pushes, dynamic coupons).
- Web (Web Push, JSON payload):
source: "releva",title,body,icon,image,badge,actions(the one button),tag,requireInteraction,renotify,silent,timestamp,idanddata.url, the link wrapped in a click-tracking redirect. TTL is Message Expire Time in seconds. - Android and iOS (FCM data message):
title,body, optionalimageUrlandbutton,target(screenwithnavigate_to_screenandnavigate_to_parameters,urlwithnavigate_to_url, orinbox),callbackUrlfor click tracking, andinbox_sync. Android TTL is Message Expire Time in hours with priorityhigh(normalwhen Silent); APNs expiration is now plus Message Expire Time.
Versioning
Section titled “Versioning”All endpoints are under /api/v0. For how versions and changes are handled, see Authentication, errors and limits.