Skip to content

Area: Developers

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.

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.

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.

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_TOKEN

Authentication 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.

  • Send JSON with content-type: application/json. The JavaScript SDK sends a form body instead, with one field formPayload = base64(encodeURIComponent(JSON.stringify(body))). Any other content type answers 400 {"message":"Request body is missing."}; a form body without formPayload answers 400 {"message":"formPayload is missing from request body"}.
  • The context object of the push is validated strictly: an unknown key answers 400, 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 empty recommenders, banners and stories with status 200. This is the most common reason a test with curl shows nothing.

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.

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.

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.

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 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 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.

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.

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.
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.
  • 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.

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.