# How your catalog gets into Releva

> The three ways products reach Releva, how a product is identified and updated, when it becomes visible, and what locale and availability mean.

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

| 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](https://releva.ai/documentation/guides/catalog/find-a-product/).

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

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

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.

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

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

## Next steps

* [Catalog API overview](https://releva.ai/documentation/reference/catalog/overview/): Send products to Releva with a working request for every endpoint.
* [Find a product in your catalog](https://releva.ai/documentation/guides/catalog/find-a-product/): Check that a product arrived and see what Releva knows about it.
* [View a product’s details, interactions and recommendations](https://releva.ai/documentation/guides/catalog/view-product-details/): Read every synced field, recent orders and recommended products.