# Let Releva pull your catalog

> The catalog endpoint you build for a full sync: the request Releva sends, the response you return, paging, retries, deletion, triggers, default URLs per platform, and POST /api/v0/products/sync.

In a full catalog sync, Releva calls an endpoint on **your** server, reads your whole catalog page by page, and then removes every product it did not see. This page is the contract for that endpoint, and for `POST /api/v0/products/sync`, which starts a sync from your system.

## When to use it

Build it when your shop is custom-built and you want Releva to pull the complete catalog on a schedule (typically once a day, overnight), as a safety net behind [Create or update products](https://releva.ai/documentation/reference/catalog/create-or-update-products/). It is not required, but it limits the time Releva’s catalog stays stale when an update is missed. Platform plugins ship this endpoint.

> **Your endpoint must return your complete catalog**
>
> About two minutes after a successful pass, any product that was not part of it is deleted from Releva, including products you sent through [Create or update products](https://releva.ai/documentation/reference/catalog/create-or-update-products/). Do not filter the response down to in-stock, visible or recently changed products: send everything, and use `available: false` for what cannot be bought right now. Nothing is deleted when a pass does not complete.

Configure its URL under **Settings › Shop & Integration › Catalog Sync**, with **Catalog Sync Type** set to **API**: see [Schedule a full catalog sync](https://releva.ai/documentation/guides/shop-settings/schedule-a-catalog-sync/).

## Authentication

Releva sends your shop’s own **Secret Key** in two headers. Your endpoint exposes your whole catalog: compare the bearer token with your shop’s Secret Key and answer `401` when it does not match.

```plaintext
authorization: Bearer $RELEVA_SECRET_KEY
x-rlv-authorization: Bearer $RELEVA_SECRET_KEY
```

`x-rlv-authorization` exists for Apache and PHP hosts that drop the standard header.

## Request

Releva sends:

```plaintext
GET {yourSyncUrl}?page=1&cursor=null
user-agent: Releva/0.0.1
content-type: application/json
authorization: Bearer $RELEVA_SECRET_KEY
x-rlv-authorization: Bearer $RELEVA_SECRET_KEY
```

* Query parameters already in your configured URL are kept; `page` and `cursor` are set on every request.
* The first request of a pass is always `page=1&cursor=null`, with the literal string `null`.
* **Both query parameters are always present** (except for the admin **Test** button, see [Triggers](https://releva.ai/documentation/reference/catalog/let-releva-pull-your-catalog/#triggers)), whichever style of paging you implement. If you page by page number, read `page` and ignore `cursor`; `page` counts up from `1`. If you page by cursor, read `cursor` and ignore `page` (it stays at `1` for the whole pass), and treat the literal value `null` as “start from the beginning”.
* **Respond within 2 minutes.** Aim for 20 to 50 products per page: small pages that answer quickly sync faster overall than large pages that time out.
* **Be consistent within a pass.** Return the pages in a stable order. A catalog that reorders itself between requests can skip or repeat products.
* Optional request-signature headers (`Signature-Agent`, `Signature-Input`, `Signature`, RFC 9421) are added only when Releva enables signing. Do not require them.

To call your endpoint the way Releva does:

```plaintext
curl 'https://demo-store.example.com/api/releva/products?page=1&cursor=null' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H "x-rlv-authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json'
```

## Response

Return HTTP status `200` with a JSON body. Your response should contain 20 to 50 products. (Releva accepts any 2xx status.)

| Field        | Type              | Required       | Notes                                                                                                               |
| ------------ | ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `products`   | array of products | yes            | The products of this page. Without it the run fails with `Invalid response "<url>": <body>`.                        |
| `pageCount`  | integer           | one of the two | Total number of pages. Send it on **every** page. Releva asks for `page+1` until `page >= pageCount`.               |
| `nextCursor` | string or `null`  | one of the two | Cursor for the next request, sent back as `cursor` while `page` stays `1`. `null` or an empty string ends the pass. |

Do not send both `pageCount` and `nextCursor`: if `pageCount` is present and not zero, it wins and your cursor is ignored. `pageCount: 0` counts as missing. With neither field the run fails with `Either nextCursor or pageCount is required in the response so we know how to iterate over results!`

A product has the same fields as in [Create or update products](https://releva.ai/documentation/reference/catalog/create-or-update-products/#product-fields). Its `id` should match the id you pass as `product.id` and `cart.products[].id` in the front-end integration, and as `carts[].products[].id` in the backend integration. Send out-of-stock products with `available: false` rather than leaving them out of the response. There are two differences from the push API: keys that are not in the schema are removed instead of failing the request, and a product that is still invalid is dropped and counted as **Invalid** in **Sync History** instead of failing the page.

> **A dropped product is deleted**
>
> Because a dropped product is not seen by the pass, it is also removed by the cleanup afterwards. A systematically malformed field, such as a price sent as a string, a `publishedAt` with no time zone offset or a locale such as `en-US`, can therefore empty large parts of your Releva catalog while your endpoint keeps answering `200`.

Page-based example:

```plaintext
{
  "pageCount": 3,
  "products": [
    {
      "id": "DEMO-1001",
      "name": "Linen Summer Shirt",
      "description": "A short description of the product.",
      "locale": "en",
      "currency": "EUR",
      "categories": ["Men/Shirts"],
      "url": "https://demo-store.example.com/products/linen-summer-shirt",
      "imageUrl": "https://demo-store.example.com/images/linen-summer-shirt.jpg",
      "publishedAt": "2026-04-15T03:21:50+00:00",
      "sku": "LSS-001",
      "stockQuantity": 12,
      "custom": {
        "string": [
          { "key": "Season", "values": ["Summer"] },
          { "key": "Size", "values": ["L"] }
        ]
      },
      "available": true,
      "listPrice": 39.9,
      "discountPrice": 29.9,
      "inventory": [
        { "location": [{ "lat": 42.6977, "lon": 23.3219 }] }
      ]
    }
  ]
}
```

Cursor-based example: a page with a next cursor, then the last page.

```plaintext
{ "nextCursor": "eyJsYXN0SWQiOiJERU1PLTEwMDEifQ==", "products": [ { "id": "DEMO-1001", "name": "Linen Summer Shirt", "listPrice": 39.9, "categories": ["Men/Shirts"], "available": true } ] }
```

```plaintext
{ "nextCursor": null, "products": [ { "id": "DEMO-1002", "name": "Linen Trousers", "listPrice": 49.9, "categories": ["Men/Trousers"], "available": false } ] }
```

> **Never answer 200 with an empty catalog**
>
> A complete-looking empty pass deletes every product of your shop. When something is wrong on your side, answer with an error status, or with a body that has no `products` array: that fails the run, and nothing is deleted.

## Timing, retries and deletion

* Each page has a **2-minute** budget that covers the request and its retries. Network errors, 5xx and 429 answers are retried with exponential back-off within that budget, up to 10 times. A timeout is not retried at once.
* When a page fails (a 4xx, a timeout, or the budget or retries used up), the run fails. Releva then retries the whole run up to **10 times** over about 50 minutes, with growing delays from 10 seconds to 15 minutes.
* Releva saves its place after every page. A retried run resumes from the next page or stored cursor. A new scheduled run starts at page 1.
* One sync per shop at a time. A trigger that arrives while a sync of the same shop and type is queued or running is skipped.
* **About 120 seconds after a complete pass, every product of the shop that the pass did not update is deleted**, including products you pushed through the API that your endpoint did not return. Return the full catalog and use `available: false` for items that are out of stock. Nothing is deleted after a failed pass.
* A shop with no sync URL, or a disabled shop, is not synced. Nothing is recorded in **Sync History** unless a run was already in progress.

## Triggers

* **Schedule**: the cron expression in **Catalog Sync Schedule**, checked every minute. Shopify shops get a random nightly schedule when they are created; other shops have none until you set one.
* **Sync Now** in the admin queues a sync at once.
* **Test** in the admin sends one `GET` with `page=1` only (no `cursor`, no timeout, no retries) and shows the answer under the URL field as **API Response:**. A non-2xx answer or a network error shows an error under the field instead.
* `POST /api/v0/products/sync` from your system, below.

### Start a full sync from your system

`POST https://releva.ai/api/v0/products/sync` queues a full sync with the shop’s configured **Catalog Sync Type** and URL. The body is ignored. If a sync for the shop is already queued or running, the call changes nothing. It authenticates with your Secret Key like the other catalog calls ([Catalog API: Authentication](https://releva.ai/documentation/reference/catalog/overview/#authentication)).

```plaintext
curl -X POST 'https://releva.ai/api/v0/products/sync' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{}'
```

It answers `202 Accepted` with `{}`. Only authentication errors (`400`) and a disabled shop (`402`) apply.

## Default URLs per platform

| Platform             | Default sync URL                                                                      |
| -------------------- | ------------------------------------------------------------------------------------- |
| Custom / other       | `{shopUrl}/api/releva/products`                                                       |
| Shopify              | Releva’s Shopify connector                                                            |
| WooCommerce, CS-Cart | `{shopUrl}/?rest_route=/releva/integration/products`                                  |
| Magento 1 and 2      | `{shopUrl}/releva/integration/products`                                               |
| OpenCart             | `{shopUrl}/index.php?route=extension/module/releva_products`                          |
| PrestaShop           | `{shopUrl}/index.php?fc=module&module=releva&controller=products&id_lang=1&ajax=true` |
| CloudCart            | `https://releva.ai/api/cloudcart/products`                                            |
| Gombashop, Shopiko   | `https://releva.ai/api/gombashop/products`                                            |

## Errors

What your endpoint’s answers do to the run:

| Your answer                             | Result                                                                                                              |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 2xx without `products`                  | The run fails: `Invalid response "<url>": <body>`                                                                   |
| 2xx without `pageCount` or `nextCursor` | The run fails: `Either nextCursor or pageCount is required in the response so we know how to iterate over results!` |
| 4xx other than 429                      | The page is not retried and the run fails. Nothing is deleted.                                                      |
| 429, 5xx or network error               | Retried with back-off within the page’s 2-minute budget, then the run fails. Nothing is deleted.                    |
| Timeout                                 | Not retried at once; the run fails. Nothing is deleted.                                                             |

A failed run is retried as a whole, up to 10 times, and resumes from the last saved page or cursor.

## Limits

* One sync per shop at a time.
* 2 minutes per page, retries included.

## Next steps

* [Schedule a full catalog sync](https://releva.ai/documentation/guides/shop-settings/schedule-a-catalog-sync/): Set the sync type, endpoint and schedule in the admin, then test and save.
* [Create or update products](https://releva.ai/documentation/reference/catalog/create-or-update-products/): Push changes between syncs so Releva is current within seconds.
* [How your catalog gets into Releva](https://releva.ai/documentation/learn/catalog/how-your-catalog-gets-into-releva/): Learn how the push and the pull work together.