Skip to content

Area: Developers

POST

Get the product blocks for a page (access token in the header)

Path
/push
Auth
Access token · browser or app
POST
/push
curl --request POST \
--url https://releva.ai/api/v0/push \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "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 page push, with the access token sent as authorization: Bearer <accessToken> instead of in the path. The JavaScript SDK uses POST /push/{accessToken} (no header, so no CORS pre-flight); server-side renderers and tests can use this form. The response carries the product blocks of the Releva page identified by context.page.token (or, without a token, by the pathname of context.page.url).

A block is returned only if it is switched on and inside its start/end time, has a product feed and a segment, matches context.page.blocks.tags (if sent), the visitor’s segment, the URL rule and the locale rule, and the caller is not a bot. Requests with a bot user agent, including curl’s default one, get "recommenders": []. A block that returns fewer products than its minimum, or a visitor in the A/B control group, gets the block with "response": []. context.mode: "debug" returns switched-off blocks too and adds query and filter. Configuration changes apply on the next push; otherwise the page configuration is cached for 60 seconds.

Only the context fields that affect product blocks are listed. The context object is strict: an undeclared key answers 400. See the events-tracking fragment for the full context (cart, profile, events, wishlist…).

object
options

Sent by the SDK (client name, version); not used for product blocks.

object
context
required
object
deviceId
string
sessionId
string
mode

debug (from ?rlv_mode=debug) returns switched-off and out-of-schedule blocks and adds query/filter. layout-edit and placement-edit are used by admin editing sessions. Other values change nothing.

string
page
object
token

Token of the Releva page (one per page type). Without it, a page whose pathname equals the pathname of url is used.

string format: uuid
url

Absolute URL of the current page. Checked against each block’s URL rule.

string
locale

ISO-639-1. Picks the title translation and the locale rule. Defaults to the domain locale.

string
currency

ISO-4217. Prices are converted to it. Defaults to the domain currency.

string
ids

Ids of the products already on the page. Discover blocks exclude them; Re-Rank blocks return only them.

Array<string>
categories
Array<string>
query
string
filter
object
tags
Array<string>
market
string
referrer
string
custom
object
blocks
object
tags

Return only blocks that have at least one of these tags.

Array<string>
product

The product on a product page.

object
id
string
cart
object
products
Array<object>
object
rid

Token of the block whose product was clicked (from rlv_rid).

string format: uuid
rpid

Id of the clicked product (from rlv_rpid).

string
rpos

Position value from rlv_rpos.

number
>= 1
pfid

Feed that filled the block (from rlv_pfid).

number

Example

{
"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": []
}
}
}

Personalized elements for the page.

Media typeapplication/json
object
recommenders
Array<object>

One product block, as returned by the page push and passed to the layout as Handlebars data.

object
token

Block token. Used as rid for clicks and token for impressions.

string format: uuid
name

Internal name.

string
title

Display title

string | null
mode
string
Allowed values: highlight discover reRank
productFeedId
integer
segmentId
integer
tags
Array<string>
meta
object
algorithm
string
cssSelector

Element the block is inserted next to (first match).

string | null
displayStrategy
string
Allowed values: beforebegin afterbegin beforeend afterend replace
displayType
string
default: static
Allowed values: static popup flyout bar custom
template

The layout. Empty when the block has no layout; the SDK then passes the block to your callback.

object
id
integer
body

Handlebars template.

string
response

Empty for the A/B control group, when fewer than the block’s minimum were found, or on a query error.

Array<object>
object
id
string
name
string
description
string
url

Product URL with rlv_rid

string
imageUrl
string
sku
string
available
boolean
categories
Array<string>
custom
object
data
object
locale
string
currency

The page currency.

string
price

Converted to the page currency.

number
listPrice
number
discountPrice
number | null
discount
number
discountPercent
number
createdAt
string format: date-time
updatedAt
string format: date-time
publishedAt
string
mergeContext

The click-tracking values, for links you build yourself.

object
rid
string format: uuid
rpid
string
rpos
integer
pfid
integer
randomize
boolean
advancedStyling
boolean
cssStyles

Overlay styling with defaults filled in.

object
banner

Overlay settings for non-static display types.

object
query

Only with mode debug.

object
filter

Only with mode debug.

object
banners
Array<object>
object
stories
Array<object>
object
push
object
vapidPublicKey
string
userId
string
gtmId
string | null
clientIp
string
userAgent
string

Example

{
"recommenders": [
{
"mode": "highlight",
"meta": {
"algorithm": "popular"
},
"displayStrategy": "beforebegin",
"displayType": "static"
}
]
}

Authentication or validation error.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Examples

{
"message": "Request body is missing."
}

The domain is disabled, or value delivery is paused because usage exceeded the plan.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Examples

{
"message": "Domain is disabled. Please reach out to support@releva.ai to enable it."
}

Unexpected error. Observed for a page.token that is not a UUID and for a relative page.url.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "An internal error occurred."
}