# How Releva connects to your shop

> The two keys of a shop, what the tracking snippet does, how the catalog pull sync works and what the Shopify app embed replaces.

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

| 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](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/).

## 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](https://releva.ai/documentation/guides/shop-settings/turn-on-the-shopify-app-embed/). 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](https://releva.ai/documentation/guides/shop-settings/schedule-a-catalog-sync/).                                                            |

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

```plaintext
<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](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#check-the-tracking-snippet-with-curl).

## The catalog pull-sync endpoint

Releva learns about products in three ways (see [How your catalog gets into Releva](https://releva.ai/documentation/learn/catalog/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:

1. Releva sends `GET {yourUrl}?page=1&cursor=null` with `authorization` and `x-rlv-authorization`, both `Bearer <secretKey>`. Your endpoint should check one of them against your secret key.
2. You answer with `{"products": [...], "pageCount": N}` for page-based catalogs, or `{"products": [...], "nextCursor": "..."}` for cursor-based ones. Releva keeps asking for `page+1` until `page >= pageCount`, or keeps sending your `nextCursor` until it is `null`.
3. 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.
4. 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.
5. 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: false` instead 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](https://releva.ai/documentation/reference/catalog/let-releva-pull-your-catalog/).

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

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

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](https://releva.ai/documentation/integrations/partner/embed-releva-in-your-platform/).

## Next steps

* [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/): Copy the two keys of your shop from the admin.
* [Turn on the Releva app embed in Shopify](https://releva.ai/documentation/guides/shop-settings/turn-on-the-shopify-app-embed/): Switch the app embed on in your Shopify theme editor.
* [Let Releva pull your catalog](https://releva.ai/documentation/reference/catalog/let-releva-pull-your-catalog/): See what the catalog endpoint Releva pulls from must return.
* [Endpoints the Releva SDKs call](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/): See every storefront endpoint the SDKs call and what they receive, for building your own client.