Skip to content

Area: Developers

Let Releva pull your catalog

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.

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. It is not required, but it limits the time Releva’s catalog stays stale when an update is missed. Platform plugins ship this endpoint.

Configure its URL under Settings › Shop & Integration › Catalog Sync, with Catalog Sync Type set to API: see Schedule a full catalog sync.

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.

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.

Releva sends:

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), 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:

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'

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

Page-based example:

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

{ "nextCursor": "eyJsYXN0SWQiOiJERU1PLTEwMDEifQ==", "products": [ { "id": "DEMO-1001", "name": "Linen Summer Shirt", "listPrice": 39.9, "categories": ["Men/Shirts"], "available": true } ] }
{ "nextCursor": null, "products": [ { "id": "DEMO-1002", "name": "Linen Trousers", "listPrice": 49.9, "categories": ["Men/Trousers"], "available": false } ] }
  • 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.
  • 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.

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

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.

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

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.

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