How Releva connects to your shop
A shop in Releva is called a domain. Everything on Settings › Shop & Integration belongs to one domain: its name and URL, its two keys, its catalog sync, its analytics and messaging settings. This page explains the pieces that connect a storefront to Releva and when you need each one.
One shop, two keys
Section titled “One shop, two keys”| Key | Where you find it | Where it goes | Secret? |
|---|---|---|---|
| Access Token | Settings › Shop & Integration › General | The browser: the tracking snippet and the JavaScript SDK. It is visible in your page source. | No |
| Secret Key | Same tab, the field below | Your server: authorization: Bearer <secretKey> on every call to https://releva.ai/api/v0. Releva also sends it to your shop when it pulls your catalog. |
Yes. Never put it in front-end code. |
Both are UUIDs generated when the shop is created, and neither can be rotated from the admin. Using one in place of the other fails with Domain with the provided secret key cannot be found. or Domain with the provided access token cannot be found. Authentication failures answer 400, not 401. Guide: Find your Access Token and Secret Key.
Three ways a storefront talks to Releva
Section titled “Three ways a storefront talks to Releva”| Shop type | What you install | What you configure |
|---|---|---|
| Shopify | The Releva app from the App Store. It adds one theme app embed, Releva.ai, that tracks behaviour and renders product blocks, banners and stories. | Switch the embed on and save the theme: Turn on the Releva app embed in Shopify. The catalog sync URL and a nightly schedule are set for you. |
| Other supported platforms (WooCommerce, Magento, OpenCart, PrestaShop, CS-Cart, CloudCart, Gombashop) | Releva’s plugin or module for the platform. It injects the snippet and serves the catalog endpoint, except on CloudCart and Gombashop, where Releva pulls the catalog from its own hosted connector rather than from your shop. | Usually nothing. The catalog sync URL is set when the shop is created. |
| Custom shop | The tracking snippet on every page, and your own calls to the API from your server. | Optionally, the catalog pull-sync endpoint and a schedule: Schedule a full catalog sync. |
The tracking snippet
Section titled “The tracking snippet”The snippet loads the Releva JavaScript SDK and calls Releva.push(accessToken, context, onSuccess, onError) on every page. The SDK posts the context (cart, product, page, profile, events) to POST /api/v0/push/{accessToken} and gets back the personalized elements for that page: product blocks, banners and stories. The access token is in the URL path, not a header, so the browser does not need a CORS pre-flight.
<script>document.addEventListener('relevaSdkLoaded', function () { Releva.push('<yourAccessToken>', { cart: { products: [] } }, function (results) { /* personalized content for this page */ }, function (error) { console.error(error); });});</script><script async type="text/javascript" src="https://releva.ai/sdk/v0/js/releva-sdk-js.min.js" onload="document.dispatchEvent(new Event('relevaSdkLoaded'));"></script>What goes into context on each page type is covered by the events documentation. A minimal push with an empty cart is enough to check that the access token works; see the install check.
The catalog pull-sync endpoint
Section titled “The catalog pull-sync endpoint”Releva learns about products in three ways (see How your catalog gets into Releva). The pull sync is the one where Releva calls you: on the cron schedule in Catalog Sync Schedule, or when someone selects Sync Now, Releva requests your catalog page by page from the URL on the Catalog Sync tab.
The legacy documentation said you “need to call” the periodical product sync API. That is backwards. You build an endpoint; Releva calls it. Pushing changes with POST /api/v0/products stays the fastest way to keep Releva current; the pull sync is the safety net that catches anything the push missed.
How a pass works:
- Releva sends
GET {yourUrl}?page=1&cursor=nullwithauthorizationandx-rlv-authorization, bothBearer <secretKey>. Your endpoint should check one of them against your secret key. - You answer with
{"products": [...], "pageCount": N}for page-based catalogs, or{"products": [...], "nextCursor": "..."}for cursor-based ones. Releva keeps asking forpage+1untilpage >= pageCount, or keeps sending yournextCursoruntil it isnull. - Each product has the same shape as in
POST /api/v0/products. Unknown keys are removed, and a product that is still invalid is dropped and counted in the Invalid column of Sync History, instead of failing the page. - Releva remembers the last page or cursor after every page. If a request fails after its retries, the run is marked failed and the queue retries it from the next page. A new scheduled run always starts from page 1.
- About 120 seconds after a complete pass, Releva deletes every product of the shop that was not updated during the pass. That includes products you sent through the API that your endpoint did not return. Return the whole catalog and mark items with
available: falseinstead of leaving them out. Nothing is deleted when a pass fails.
Only one sync per shop runs at a time; a second trigger while one is queued or running is skipped. The full request and response contract, timeouts and retries are in the reference.
Default sync URLs
Section titled “Default sync URLs”When a shop is created, Releva fills in the sync URL for its platform. Custom shops get {shopUrl}/api/releva/products; the platform plugins serve their own paths (for example /?rest_route=/releva/integration/products on WooCommerce and /releva/integration/products on Magento). Shopify shops point at Releva’s own Shopify connector, and CloudCart and Gombashop (or Shopiko) shops at Releva-hosted connectors on releva.ai. Shopify and Valival shops get a random nightly schedule between 00:00 and 04:59. Other platforms have no schedule until you set one.
Schedule
Section titled “Schedule”Catalog Sync Schedule is a five-field cron expression. The admin says it is evaluated in UTC, and the Next sync label under the field converts the next run to your browser’s local time. The scheduler checks every minute which shops’ expressions match and queues one sync per shop and sync type.
Reading your shop from the API
Section titled “Reading your shop from the API”Partner apps can read a shop’s ids, tokens and configured pages with GET /api/v0/domains, authenticated with the secret key. The response includes the secret key itself, so this call is server-to-server only. See Embed Releva in your platform.