Endpoints the Releva SDKs call
Used byJavaScript SDK, Shopify, Magento 2, Magento 1, PrestaShop, OpenCart, Partner platforms, Mobile SDKs, iOS (Swift), Flutter, React Native, Android (Kotlin)
The SDK makes these calls. You only need this page if you build your own client: a storefront without the Releva JavaScript SDK, a block you render yourself, or an app that does not use a Releva mobile SDK. With an SDK installed, you call nothing on this page directly.
- Web: JavaScript SDK reference
- Apps: Mobile SDKs overview, iOS (Swift) SDK reference, React Native SDK reference, Connect your Flutter app, Connect your Android app
Product blocks, banners and stories have no endpoint of their own. They reach the page or screen inside the page push response, and the client reports back through the impressions and events endpoints.
Which SDK calls which endpoint
Section titled “Which SDK calls which endpoint”All calls go to https://releva.ai/api/v0 (or https://<realm>.releva.ai/api/v0). The JavaScript SDK puts the access token in the path. The iOS, Flutter and React Native SDKs call the same routes without the path segment and send the token in a header instead.
| Endpoint | JavaScript SDK | Mobile SDKs | What it does |
|---|---|---|---|
POST /push/{accessToken}, POST /push |
Every Releva.push(); Releva.recommenderClicked() |
Every track* call; cart and wishlist changes after the first call |
Sends the page or screen context. Returns recommenders, banners, stories and, when on, nps, search and chatBot. |
POST /impressions/{accessToken}, POST /impressions |
When a block or banner it drew becomes visible | When a banner is shown | Records product block and banner impressions. |
POST /push/events/{accessToken}, POST /push/events |
Banner clicks and closes, story and NPS widget events, page engagement | Banner clicks and closes, story events | Records one event per request. |
POST /pushSubscriptions/{accessToken} |
After a push, with serviceWorkerUrl and granted permission |
Registers a web push subscription. See Push notifications API. | |
POST /appPush/tokens |
registerPushToken |
Registers an app push token. See Push notifications API. | |
POST /searchAsYouType/{accessToken} |
Releva.searchAsYouType() and the search dropdown |
See Search as you type API. | |
POST /subscribe/request, POST /subscribe/check |
Releva.requestSubscribe(), Releva.checkSubscribed() |
See Consent API. | |
POST /nps/{token}/submissions |
The NPS widget | submitNpsResponse |
See Surveys API. |
/inbox/* (six routes) |
The App Inbox | See Inbox API. | |
GET of the push’s callbackUrl |
Push tap tracking | No authentication; the URL carries an encrypted payload. |
The rest of this page covers the first three rows: the push response for product blocks, banners and stories, and the calls that report back.
Authentication
Section titled “Authentication”Every call on this page takes your shop’s access token, the public key that ships in your page source. Never put the secret key in a browser or an app. Find the token under Settings › Shop & Integration (Find your Access Token and Secret Key).
Send it in the path, POST /push/{accessToken}, as the JavaScript SDK does, or as a header on the path without it, as the mobile SDKs do:
authorization: Bearer $RELEVA_ACCESS_TOKENAuthentication failures on the push answer 400:
| Problem | Message |
|---|---|
| No token in the path and no header | 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 | Domain with the provided access token cannot be found. |
A disabled shop answers 402 Domain is disabled. Please reach out to support@releva.ai to enable it.; a shop whose usage exceeded its plan answers 402 Value delivery is paused for this domain because usage exceeded the plan limit. Please raise your limit or reach out to support@releva.ai to resume.
Request format
Section titled “Request format”- Send JSON with
content-type: application/json. The JavaScript SDK sends a form body instead, with one fieldformPayload=base64(encodeURIComponent(JSON.stringify(body))). Any other content type answers400 {"message":"Request body is missing."}; a form body withoutformPayloadanswers400 {"message":"formPayload is missing from request body"}. - The
contextobject of the push is validated strictly: an unknown key answers400, for example{"message":"The object 'page' contains forbidden keys: 'color'."}. - Send a browser user agent. Requests whose user agent is a bot, including curl’s default
curl/x.y, get emptyrecommenders,bannersandstorieswith status200. This is the most common reason a test with curl shows nothing.
The page push
Section titled “The page push”POST /push/{accessToken}
The fields of context that decide what comes back:
| Field | Type | Effect |
|---|---|---|
page.token |
UUID | The Releva page (Token: on the page’s list). Without it, Releva matches a page by the pathname of page.url against the page’s URL Path; without either, nothing is returned. |
page.url |
absolute URL | Used for the page match above and for each block’s URL filter. Must be absolute (https://...): a relative URL answers 500. The Swift SDK sends no page URL, so URL filters do not apply in iOS apps. |
page.locale |
ISO-639-1 (en) |
Picks the title translation and the Locales to Display rule. Defaults to the shop locale. en-US answers 400 page.locale must be a valid ISO-639-1 code! Got en-US instead. |
page.currency |
ISO-4217 | Prices in the response are converted to it. Defaults to the shop currency. |
page.ids |
string[] | Product ids already on the page. Discover blocks exclude them, Re-Rank blocks return only them, Highlight blocks ignore them. A Re-Rank block without ids returns no products. |
page.blocks.tags |
string[] | Return only product blocks, banner blocks and stories that carry at least one of these tags. Product blocks without tags are dropped when this is sent. |
product.id, cart.products, page.categories, page.query |
Context for the feed’s algorithm (similar products, bought together, search). | |
deviceId, sessionId, profile |
Who the visitor is: segment membership and the A/B control group. | |
mode |
"debug" |
Returns switched-off and out-of-schedule product blocks too and adds query and filter to each. The JavaScript SDK sends it when the page URL has ?rlv_mode=debug. |
rid, rpid, rpos, pfid |
Click attribution from the previous page; see Record a product block click. |
curl -X POST "https://releva.ai/api/v0/push/$RELEVA_ACCESS_TOKEN" \ -H 'content-type: application/json' \ -H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36' \ -d '{ "context": { "deviceId": "demo-device-pb-1", "sessionId": "demo-session-pb-1", "page": { "token": "3f1c2a9e-5b7d-4c1e-9a2b-7d6e5f4a3b21", "url": "https://demo-store.example.com/products/linen-summer-shirt", "locale": "en", "currency": "EUR" }, "product": { "id": "DEMO-1001" }, "cart": { "products": [] } } }'The response is 200 with recommenders (product blocks), banners and stories, each described below. Every array can be empty: no page matched, nothing passed the rules, the visitor is in an A/B control group, or the caller is a bot.
The page configuration is cached for 60 seconds per access token and page. Saving a block in the admin clears the cache, so an edit shows on the next push; a block that starts or ends by schedule can take up to a minute.
Check the tracking snippet with curl
Section titled “Check the tracking snippet with curl”Use this to prove that an access token is valid and the shop is running before you debug the storefront snippet. This is the smallest valid request:
curl -sS -X POST "https://releva.ai/api/v0/push/$RELEVA_ACCESS_TOKEN" \ -H 'content-type: application/json' \ --data '{"context":{"cart":{"products":[]}}}'Response 200:
{ "recommenders": [], "banners": [], "stories": [], "push": { "vapidPublicKey": "<vapid-public-key>" }, "gtmId": null, "clientIp": "203.0.113.10", "userAgent": "curl/8.7.1"}A 200 means the token and the shop are fine. recommenders, banners and stories stay empty here: the request carries no page token and uses curl’s default user agent. Every successful call records an anonymous page view, so don’t run it in a loop. For the error messages, see Authentication and Errors.
Product blocks in the /push response
Section titled “Product blocks in the /push response”recommenders holds one object per product block, in the block’s priority order on the page. One block, one product shown (cssStyles cut):
{ "recommenders": [ { "token": "8b0e6f3a-2c4d-4e5f-9a1b-3c2d1e0f9a8b", "name": "Demo popular on product page", "title": "Popular right now", "mode": "highlight", "productFeedId": 37, "segmentId": 1, "tags": [], "meta": { "algorithm": "popular" }, "displayType": "static", "cssSelector": "#releva-demo-block", "displayStrategy": "beforeend", "template": { "id": 34, "body": "<div class=\"rlv-demo-block\"><h3>{{title}}</h3><ul>{{#each response}}<li><a href=\"{{url}}\">{{name}}</a> <span>{{price}} {{currency}}</span></li>{{/each}}</ul></div>" }, "randomize": false, "advancedStyling": false, "response": [ { "id": "DEMO-1003", "name": "Leather Sandals", "description": "Hand-stitched leather sandals with a cushioned sole.", "url": "https://demo-store.example.com/products/leather-sandals?rlv_rid=8b0e6f3a-2c4d-4e5f-9a1b-3c2d1e0f9a8b&rlv_rpid=DEMO-1003&rlv_rpos=1&rlv_pfid=37", "imageUrl": "https://demo-store.example.com/images/leather-sandals.jpg", "sku": "DEMO-1003-40", "available": true, "categories": ["Women/Shoes/Sandals"], "custom": { "string": [{ "key": "size", "values": ["38", "40"] }], "numeric": [], "date": [] }, "locale": "en", "currency": "EUR", "listPrice": 59, "discountPrice": null, "price": 59, "discount": 0, "discountPercent": 0, "mergeContext": { "rid": "8b0e6f3a-2c4d-4e5f-9a1b-3c2d1e0f9a8b", "rpid": "DEMO-1003", "rpos": 1, "pfid": 37 }, "createdAt": "2026-10-20T20:05:48.278Z", "updatedAt": "2026-10-20T20:05:48.278Z" } ] } ]}| Field | Meaning |
|---|---|
token |
The block’s id. It is the rid of a click and the token of an impression. |
name, title |
Admin name; the title for page.locale (its translation when one exists), or null. |
mode |
highlight, discover or reRank. |
productFeedId, segmentId, meta.algorithm, tags |
The feed and segment that filled the block, the feed’s algorithm, the block’s tags. |
displayType |
static (inline), popup, flyout, bar or custom. Non-static blocks also carry a banner object with the overlay settings. |
cssSelector, displayStrategy |
Where to insert: the first match of document.querySelector(cssSelector), at beforebegin, afterbegin, beforeend, afterend or replace (hide the target and insert after it). cssSelector is null when not set. |
template |
The layout as a Handlebars template in body. Absent when the block has no layout. |
response |
The products. Empty for a visitor in the A/B control group, when the feed found fewer products than the block’s minimum, or when the query failed. |
randomize, advancedStyling, cssStyles |
Shuffle (already applied), and the overlay styling with defaults filled in. |
query, filter |
Only with mode: "debug": the search query and the feed rules. |
Each product in response has the catalog fields (id, name, description, url, imageUrl, sku, available, categories, custom, data, locale, createdAt, updatedAt, publishedAt), the prices converted to page.currency (currency, listPrice, discountPrice, price, discount, discountPercent), the click parameters appended to url, and the same values in mergeContext for links you build yourself.
Which blocks come back. In this order: the page is found by page.token, else by pathname; the block is on and inside its start and end time (skipped in debug mode); it has a feed and a segment; it matches page.blocks.tags if sent; the visitor matches the audience (segment, inverted by Exclude, combined with the profile filter); the URL passes the block’s URL filter (text fragments separated by |, substring match; no page.url means the rule passes); the user agent is not a bot; page.locale is in the block’s locales or the list is empty. More on these rules in How product blocks work.
Draw a block yourself. When a block has no template or no cssSelector, the JavaScript SDK does not draw it and passes it to the Releva.push callback instead. Render response with your own markup and keep each product’s url as returned so that clicks are recorded. Then report impressions yourself: the SDK only tracks the blocks it drew.
Record a product block click
Section titled “Record a product block click”A click is recorded on the next push, from the parameters Releva appended to the product URL: rlv_rid (block token), rlv_rpid (product id), rlv_rpos (position) and rlv_pfid (feed id). The JavaScript SDK copies them from the landing URL into context.rid, rpid, rpos and pfid. Releva writes a recommenderClick event and attributes the visitor’s cart additions and purchases of the next day to the block.
curl -X POST "https://releva.ai/api/v0/push/$RELEVA_ACCESS_TOKEN" \ -H 'content-type: application/json' \ -H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36' \ -d '{ "context": { "deviceId": "demo-device-pb-1", "sessionId": "demo-session-pb-1", "rid": "8b0e6f3a-2c4d-4e5f-9a1b-3c2d1e0f9a8b", "rpid": "DEMO-1003", "rpos": 1, "pfid": 37, "page": { "token": "3f1c2a9e-5b7d-4c1e-9a2b-7d6e5f4a3b21", "url": "https://demo-store.example.com/products/leather-sandals?rlv_rid=8b0e6f3a-2c4d-4e5f-9a1b-3c2d1e0f9a8b&rlv_rpid=DEMO-1003&rlv_rpos=1&rlv_pfid=37" }, "product": { "id": "DEMO-1003" } } }'Response: 200 with the usual push body for the landing page. rid must be a UUID and rpos a number of 1 or more. For a click that does not load a new page (a quick-view dialog in a single-page app), the JavaScript SDK has Releva.recommenderClicked(rpid, rid): it sends a push with only those two fields.
Banners in the /push response
Section titled “Banners in the /push response”banners holds one object per banner block that passed the serving rules (When a block is served), in priority order and cut to the page’s Max Banners Displayed. The client decides when to show each block from trigger.
{ "banners": [ { "token": "7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b", "bannerId": 1, "design": null, "segmentId": 3, "displayType": "bar", "delaySeconds": null, "scrollPercentage": 30, "cssSelector": "", "trigger": "scrollPercentage", "leaveIntentBackButton": false, "name": "Demo summer sale bar", "displayStrategy": "afterbegin", "html": "<div>…<a href=\"https://demo-store.example.com/collections/summer-sale?rlv_bid=7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b\">Shop the sale</a></div>", "tags": [], "mergeContext": {}, "displayPosition": null, "advancedStyling": false, "cssStyles": { "overlayColor": "rgba(0,0,0,0.4)", "cardBackgroundColor": "#fefefe", "closeButtonSymbol": "X", "closeButtonColor": "#000", "closeButtonBackgroundColor": "#fff", "customCss": "" } } ]}| Field | Meaning |
|---|---|
token |
The banner block’s UUID. Send it back as token in an impression and as attributions.bannerBlockId in a banner event. |
bannerId |
The banner’s numeric id. Send it back as a string. |
name |
The block’s admin name, for debugging. |
segmentId |
The id of the banner’s segment. Send it back as a string in an impression. |
design |
The design document in the Unlayer format the app SDKs draw from (a banner built in the Releva builder also carries the builder’s own document), or null for an HTML banner. On the web, render html. |
displayType |
static, popup, flyout, bar or custom: the Display mode. |
trigger |
One of immediately, scrollPercentage, delaySeconds, leaveIntent, wishlistChanged, cartChanged. Always immediately for static. |
delaySeconds, scrollPercentage, leaveIntentBackButton |
Parameters for the matching trigger; null or false otherwise. |
cssSelector, displayStrategy |
For static blocks: where to insert the HTML, and how (beforebegin, afterbegin, beforeend, afterend or replace, the Insert strategy). |
html |
The banner’s HTML, already personalised with the visitor’s merge tags. Every trackable link carries rlv_bid=<token>, and rlv_u when the link leaves the shop’s host. |
tags |
Tag names, for clients that filter by tag. |
mergeContext |
Tracking context the SDK attaches to links. |
displayPosition, advancedStyling, cssStyles |
The Appearance settings: placement (top, bottom, left, right or null for automatic), whether the author styled the block, and the overlay, card and close-button styles. cssStyles is always complete: Releva merges the block’s own values over the standard defaults. Numeric values are strings without a unit (the SDK appends px). |
To report what the visitor did with a banner, send an impression when it is shown and a banner event when it is clicked or closed.
Stories in the /push response
Section titled “Stories in the /push response”stories holds the stories for the page or screen, on the web and in apps. It is empty when none of the display rules pass (When a story is shown). The client decides when to open the story from trigger.
{ "stories": [ { "token": "7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b", "storyId": 1, "name": "Demo summer lookbook", "trigger": "delaySeconds", "leaveIntentBackButton": false, "delaySeconds": 3, "scrollPercentage": null, "autoPlayDurationSeconds": 6, "endBehavior": "dismiss", "progressIndicatorColor": "#333333", "progressIndicatorInactiveColor": "#33333340", "tags": [], "slides": [ { "id": 11, "position": 0, "html": "<div>…<a href=\"https://demo-store.example.com/collections/summer?rlv_stid=7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b\">Shop now</a></div>", "design": null, "durationSeconds": 6, "actionType": "none", "actionUrl": null, "actionLabel": null } ], "mergeContext": {} } ]}| Field | Meaning |
|---|---|
token |
The story’s UUID. Send it back as attributions.storyId on every story event. |
storyId, name |
The admin id and name, for debugging. |
trigger |
One of immediately, scrollPercentage, delaySeconds, leaveIntent, wishlistChanged, cartChanged. |
delaySeconds, scrollPercentage, leaveIntentBackButton |
Parameters for the matching trigger; null or false otherwise. |
autoPlayDurationSeconds |
Default time per slide, 1 to 60. |
endBehavior |
dismiss, loop or stayOnLast. |
progressIndicatorColor, progressIndicatorInactiveColor |
Hex colours for the progress bars; may be null. |
tags |
Tag names, for clients that filter by tag. |
slides[] |
Sorted by position. html is already personalised with the visitor’s merge tags, and every trackable link carries rlv_stid=<token> (and rlv_u when the link leaves the shop’s host). durationSeconds is the slide override or the story default. |
slides[].actionType, actionUrl, actionLabel |
none, deepLink, webUrl or dismiss, with the target and label. Meant for mobile clients; the admin form has no field for them, so they are none / null unless set through other tooling. |
mergeContext |
Tracking context the SDK attaches to story links. |
Report impressions
Section titled “Report impressions”POST /impressions/{accessToken}
Records one recommenderImpression event per product block and one bannerImpression event per banner. The JavaScript SDK calls it when a block or banner it drew becomes visible (at least 25% of a product block), once per block per page load; the mobile SDKs call it when a banner is shown. Call it yourself only for what you rendered.
| Field | Required | Notes |
|---|---|---|
recommenders |
one of recommenders / banners |
Items { token, productFeedId, segmentId } copied from the block; no other keys |
banners |
one of recommenders / banners |
Items { token, bannerId, segmentId } copied from the banner; no other keys |
profileId or deviceId |
one of the two | The visitor; the SDK sends the profile id when known, else the device id |
sessionId, url, email, phoneNumber |
no |
productFeedId, bannerId and segmentId must be strings here, although the push returns them as numbers.
curl -X POST "https://releva.ai/api/v0/impressions/$RELEVA_ACCESS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "recommenders": [ { "token": "8b0e6f3a-2c4d-4e5f-9a1b-3c2d1e0f9a8b", "productFeedId": "37", "segmentId": "1" } ], "banners": [ { "token": "7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b", "bannerId": "1", "segmentId": "3" } ], "deviceId": "demo-device-pb-1", "sessionId": "demo-session-pb-1", "url": "https://demo-store.example.com/products/linen-summer-shirt" }'Response: 200 {}. Impressions are not deduplicated by the server.
| Cause | Status | Body |
|---|---|---|
Neither profileId nor deviceId |
400 | {"error":"One of profileId or deviceId is required"} |
Neither recommenders nor banners |
400 | {"error":"At least one of banners or recommenders must be provided"} |
productFeedId sent as a number |
400 | {"message":"The 'recommenders[0].productFeedId' field must be a string."} |
| Extra key in an item | 400 | {"message":"The object 'recommenders[0]' contains forbidden keys: 'position'."} |
The handler’s own checks answer with an error key; validation and authentication answer with message.
Banner and story events
Section titled “Banner and story events”POST /push/events/{accessToken}
Send one request per event with content-type: application/json.
curl -X POST "https://releva.ai/api/v0/push/events/$RELEVA_ACCESS_TOKEN" \ -H 'content-type: application/json' \ -d '{ "deviceId": "demo-device-pb-1", "sessionId": "demo-session-pb-1", "action": "bannerClick", "attributions": { "bannerBlockId": "7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b", "bannerId": "1" }, "page": { "url": "https://demo-store.example.com/" } }'| Field | Required | Meaning |
|---|---|---|
deviceId |
yes | The visitor’s device id, the same value you send as context.deviceId on the push. Also the key for the Show until click memory. |
sessionId |
yes | The visitor’s session id. |
action |
yes | One of the actions below. |
attributions.bannerBlockId, attributions.bannerId |
for banner events | The block token and the bannerId (as a string) from the push response. Send both. |
attributions.storyId |
for story events | The story token from the push response. |
profileId |
no | The known profile id, when the visitor is identified. One of profileId or deviceId must be non-empty. |
page.url, page.token |
no | The page the event happened on. |
action |
Send it when | Counted as |
|---|---|---|
bannerClick |
The visitor follows a link in the banner | Clicks; also attributes later cart adds and orders to the block |
bannerClose |
The visitor closes the banner | Closes |
storyImpression |
The story opens | Impressions |
storySlideView |
A slide becomes visible | Slide Views |
storySlideClick |
The visitor follows a link or action in a slide | CTA Clicks; also attributes later cart adds and orders to the story |
storyComplete |
The last slide finishes | Completions |
storyClose |
The visitor closes the story | Closes |
Banner impressions do not go here: send them to /impressions. A click and a close also set the Show until click memory for the device; see How banners work and How stories work. A banner click is also detected when the visitor lands on an rlv_bid link; the two reports are deduplicated by block and device, so sending bannerClick does not double count.
Response: 202 {}. The event is stored asynchronously and appears in Data Platform › Events and on the block’s or story’s statistics shortly after. An unknown bannerBlockId or storyId is also accepted with 202, stored as an ordinary event and not counted anywhere, so check the ids you send back.
Message (400) |
Cause |
|---|---|
The access token you provided is invalid. |
The token is not a shop’s access token. |
The 'deviceId' field is required. The 'sessionId' field is required. |
Required fields missing; several problems are joined with a space. |
One of profileId or deviceId is required. |
deviceId was sent empty and there is no profileId. |
The 'action' field must be a string. |
Wrong type. |
Errors
Section titled “Errors”| Status | When |
|---|---|
200 |
Push and impressions succeeded. Empty arrays in a push response are also a success. |
202 |
An event was accepted. |
400 |
Authentication failed, validation failed, or the body could not be parsed. One message, as above. |
402 |
The shop is disabled or its delivery is paused. |
500 |
{"message":"An internal error occurred."}. Seen for a page.token that is not a UUID and for a relative page.url; fix the request rather than retrying. |
Limits
Section titled “Limits”- Body size: 800 KB JSON, 2 MB form-encoded.
- Rate limits: none.
- Per page, at most 10 running product blocks by default. This is enforced when a block is saved or switched on in the admin, not on the push.
- Configuration cache: 60 seconds, cleared when a block is saved.
Versioning
Section titled “Versioning”All endpoints are under /api/v0. context is validated strictly, so send new context keys only after they appear in the reference. Changes are listed in the API changelog.