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.
When to use it
Section titled “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. 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.
Authentication
Section titled “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.
authorization: Bearer $RELEVA_SECRET_KEYx-rlv-authorization: Bearer $RELEVA_SECRET_KEYx-rlv-authorization exists for Apache and PHP hosts that drop the standard header.
Request
Section titled “Request”Releva sends:
GET {yourSyncUrl}?page=1&cursor=nulluser-agent: Releva/0.0.1content-type: application/jsonauthorization: Bearer $RELEVA_SECRET_KEYx-rlv-authorization: Bearer $RELEVA_SECRET_KEY- Query parameters already in your configured URL are kept;
pageandcursorare set on every request. - The first request of a pass is always
page=1&cursor=null, with the literal stringnull. - 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
pageand ignorecursor;pagecounts up from1. If you page by cursor, readcursorand ignorepage(it stays at1for the whole pass), and treat the literal valuenullas “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'Response
Section titled “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. 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 } ] }Timing, retries and deletion
Section titled “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: falsefor 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
Section titled “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
GETwithpage=1only (nocursor, 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/syncfrom your system, below.
Start a full sync from your system
Section titled “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).
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
Section titled “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
Section titled “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
Section titled “Limits”- One sync per shop at a time.
- 2 minutes per page, retries included.