How your catalog gets into Releva
Releva keeps one product catalog per shop (domain). Recommendations, product feeds, catalog triggers, segments and search all read from it. This page explains how products get there and what happens when you send the same product twice.
Three ways in
Section titled “Three ways in”| Method | Who drives it | Best for |
|---|---|---|
| Platform connector (Shopify, WooCommerce, Magento and others) | Releva. The connector imports the catalog on install, resyncs it on a schedule and pushes single products when they change. | Shops on a supported platform. No code. |
| Catalog sync (pull) | Releva calls a URL you provide, on a schedule or on demand. Three sync types: API (a paged JSON endpoint you build), Facebook CSV Feed and Facebook XML Feed. Configure it in Settings › Shop & Integration › Catalog Sync. | Custom shops that already have a product feed. |
| Catalog API (push) | You call POST /api/v0/products whenever a product changes. |
Headless shops and real-time updates. |
You can combine them. A shop on a connector can still push availability changes through the API.
Everything the shop sends lands in the same place. The admin Data Platform › Products page shows the stored result: see Find a product in your catalog.
A product is identified by its id
Section titled “A product is identified by its id”Releva stores one document per id per shop. Nothing else is part of the key: not the locale, not the currency, not the market.
- Send the same
idagain and you update the existing product. - Send the same
idwith a differentlocaleand you overwrite the first document. The previous language is gone. - A catalog in several languages or markets needs one
idper language or market, for example1001_enand1001_de. Releva’s own connectors use{productId}_{locale}or{productId}_{locale}_{market}. - To delete a product, call
DELETE /api/v0/products/{id}with that exact stored id.
Updates merge, with four exceptions
Section titled “Updates merge, with four exceptions”POST /api/v0/products is an upsert. It creates the product if it is new; otherwise it merges the fields you send into the stored document. Fields you leave out keep their stored value, so you can send a partial object. Four fields behave differently:
| Field | When you leave it out |
|---|---|
discountPrice |
Cleared. The product is no longer on sale. To take a product off sale, send it without discountPrice. |
custom |
Replaced by an empty set. Send all custom fields every time. |
variants |
Replaced by one variant built from the product itself. Send all variants every time. |
locale and currency |
Reset to the shop’s default locale and currency, not the previous value. |
The required fields id, name, listPrice, categories and available must be in every request, even for a partial update. categories may be an empty array.
Releva derives a few fields for you: price (the discount price when set, else the list price), discount and discountPercent, category_level_1…n custom fields from your category paths, and createdAt / updatedAt. Do not send them; unknown keys are rejected.
If you only need to change stock state, use POST /api/v0/products/availability. It changes available and nothing else, and it never creates a product.
Writes are asynchronous
Section titled “Writes are asynchronous”Every catalog endpoint answers 202 Accepted with an empty object as soon as the request is validated and queued. The product is written a few seconds later. On a healthy system, products are searchable within about 10 seconds.
Because of that:
- A
202means the payload was valid, not that the product is stored. Check the Products page or your own read path. - Validation errors are synchronous and come back as
400with a message. Errors after the202(for example a storage failure) are retried by Releva and are not reported to the caller. - A delete of an unknown id and an availability update for an unknown id both answer
202and do nothing.
Full syncs delete what they do not see
Section titled “Full syncs delete what they do not see”When a catalog sync run finishes successfully, Releva deletes, about two minutes later, every product of the shop that the run did not update. Your sync endpoint or feed must therefore return the complete catalog on every run. Products you push through the API between syncs are kept only if the next sync also returns them.
Trigger a sync on demand with POST /api/v0/products/sync or Sync Now on the Catalog Sync settings tab. A second trigger while one is queued or running has no effect.
Locales, currencies, availability and prices
Section titled “Locales, currencies, availability and prices”- Locale is a two-letter ISO-639-1 code (
en,bg). Currency is an ISO-4217 code (EUR). Both default to the shop’s settings. The first product sent in a new locale or currency registers it on the shop, which is what the admin filters list. - Available is a boolean. The list shows it as
True/False, the detail table asyes/no, and product cards as In stock/Out of stock. A change fromtruetofalseor back fires an out-of-stock or in-stock catalog event, which catalog triggers and back-in-stock campaigns use. - Prices:
listPriceis required and must be 0 or more.discountPriceis optional. Releva accepts a discount price higher than the list price, but stores a negative discount; keep it lower. Price changes fire price-increase and price-decrease catalog events. - Stock quantity is optional and informational. Availability, not stock quantity, decides whether a product is recommended.