Skip to content

Area: Developers

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.

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.

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 id again and you update the existing product.
  • Send the same id with a different locale and you overwrite the first document. The previous language is gone.
  • A catalog in several languages or markets needs one id per language or market, for example 1001_en and 1001_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.

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.

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 202 means 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 400 with a message. Errors after the 202 (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 202 and do nothing.

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 as yes/no, and product cards as In stock/Out of stock. A change from true to false or back fires an out-of-stock or in-stock catalog event, which catalog triggers and back-in-stock campaigns use.
  • Prices: listPrice is required and must be 0 or more. discountPrice is 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.