Create or update products
POST /api/v0/products creates the products you send, or updates them when Releva already has them. It is the main way Releva learns about changes in your catalog.
When to use it
Section titled “When to use it”Call it whenever your catalog changes: a new product, a new price, a product that goes out of stock or comes back in stock. This is the primary way Releva learns about changes in your catalog. Platform plugins already call it for you; you need it when your shop is custom-built.
- To change only
available, Update product availability is lighter. - To remove a product for good, use Delete a product. A product that is only out of stock stays in the catalog with
available: false. - As a safety net for changes you miss, also build the endpoint described in Let Releva pull your catalog.
Authentication
Section titled “Authentication”Send your shop’s Secret Key as a bearer token: authorization: Bearer $RELEVA_SECRET_KEY. Never use it in a browser or an app. Find it under Settings › Shop & Integration (Find your Access Token and Secret Key). The error messages are in Catalog API: Authentication.
Request
Section titled “Request”POST https://releva.ai/api/v0/products with content-type: application/json and a body { "products": [ ... ] } that holds at least one product. The maximum body is 800 KB: split larger catalogs into several requests, a few hundred products per request.
The example sends one product in its UK English version, on sale, with every common field. For variants, see Variants.
curl -X POST 'https://releva.ai/api/v0/products' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json' \ -d '{ "products": [ { "id": "DEMO-1001_en_uk", "name": "Linen Summer Shirt", "description": "A breathable linen shirt for warm days.", "locale": "en", "currency": "GBP", "listPrice": 39.90, "discountPrice": 29.90, "stockQuantity": 25, "sku": "DEMO-1001-M", "categories": ["Men/Shirts", "Summer"], "available": true, "url": "https://demo-store.example.com/uk/products/linen-summer-shirt", "canonicalUrl": "https://demo-store.example.com/products/linen-summer-shirt", "imageUrl": "https://demo-store.example.com/images/linen-summer-shirt.jpg", "publishedAt": "2026-05-01T09:00:00Z", "marketHandle": "uk", "markets": ["GB"], "data": { "badge": "New in" }, "custom": { "string": [ { "key": "brand", "values": ["Demo Basics"] }, { "key": "color", "values": ["white", "sand"] } ], "numeric": [{ "key": "size", "values": [38, 40, 42] }], "date": [{ "key": "promoUntil", "values": ["2026-11-01T00:00:00Z"] }] }, "inventory": [ { "location": [{ "lat": 42.6977, "lon": 23.3219 }] } ] } ] }'Product fields
Section titled “Product fields”A product is validated strictly: a key that is not in this table is rejected. Put extra data in custom or data.
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | Identifies the stored product in your shop. One id per language and market; see Languages, currencies and markets. Delete a product takes the same id. |
name |
string | yes | |
listPrice |
number | yes | The regular price, 0 or more. |
categories |
array of strings | yes | Category paths separated by /, for example "Men/Shirts". May be empty. |
available |
boolean | yes | true when the product can be bought. |
description |
string | no | |
locale |
string | no | ISO-639-1 language code (en, not en-US). Default: your shop’s language. |
currency |
string | no | ISO-4217 code (EUR). Default: your shop’s currency. |
discountPrice |
number | no | If the product is on sale, the sale price, 0 or more. It must be lower than listPrice (a higher one is accepted but stores a negative discount). If the product is not on sale, do not include this field. |
stockQuantity |
integer | no | Units left, 0 or more. |
sku |
string | no | The SKU of the product, or of the variant shoppers see first. |
url |
string | no | Absolute URL of the product page, as a shopper in this language and market sees it. |
canonicalUrl |
string | no | Absolute URL without a language or market prefix. Ad catalog feeds use it as the base link; without it they use url. |
imageUrl |
string | no | Absolute image URL. Default: your shop’s default product image. |
publishedAt |
string | no | When the product went on sale. ISO-8601 with seconds and a zone: 2026-05-01T09:00:00Z, 2026-05-01T09:00:00.000Z or 2026-05-01T12:00:00+0300. |
marketHandle |
string | no | Your name for the market this product belongs to, for example uk. See Languages, currencies and markets. |
markets |
array of strings | no | ISO-3166-1 alpha-2 country codes in upper case (["FR", "DE"]). Anything else is rejected. |
groupId |
string | no | The product all versions of this product belong to. Used only together with a non-empty variants. See Variants. |
variants |
array of objects | no | One entry per variant. See Variants. |
custom |
object | no | Custom fields to filter, group and personalize on. See The custom object. |
data |
object | no | Any JSON you want back with the product in product block responses, for example { "badge": "New in" }. Releva does not search or filter on it. |
inventory |
array of objects | no | Stock locations: [{ "location": [{ "lat": 42.6977, "lon": 23.3219 }] }]. |
inventory[].location[].lat |
number | no | Latitude of the location in decimal notation, for example 42.6977. |
inventory[].location[].lon |
number | no | Longitude of the location in decimal notation, for example 23.3219. |
The body can also carry deleteMissingVariants (boolean) next to products. It is deprecated: it is accepted for older integrations and has no effect. Remove variants you no longer sell from the variants array, and remove products you no longer sell with Delete a product.
Variants
Section titled “Variants”Send one product per product page and describe its variants in variants. The product keeps what is shared (name, description, categories, URL); each variant carries what differs. New integrations should prefer the variants array: it keeps one entry per product page in recommenders and search instead of one entry per variant, and the Meta catalog sync uses it to build variant-level catalog items.
| Variant field | Type | Required | Notes |
|---|---|---|---|
variantId |
string | yes | Your id for the variant. |
sku |
string | no | |
listPrice |
number | no | 0 or more. |
discountPrice |
number | no | 0 or more. |
available |
boolean | no | |
stockQuantity |
integer | no | 0 or more. |
imageUrl |
string | no | Absolute URL, when the variant has its own image. |
barcode |
string | no | GTIN, EAN or similar. |
optionValues |
array of objects | no | One { "name": "Size", "value": "M" } per option. No other key. |
Rules to know:
- Send
groupIdandvariantstogether. Without a non-emptyvariants, Releva ignores yourgroupIdand uses the product’s ownid. Withvariantsbut nogroupId, the group is the product’sid. - A product sent without
variantsis stored as one variant built from the product itself. - The product-level
listPrice,discountPrice,available,stockQuantity,skuandimageUrlstay the values Releva shows. Set them to the variant a shopper sees first, usually the first available one. - Use the same
groupIdfor every language and market version of one product. The Meta catalog sync usesgroupId,variantsandmarketsto build per-variant and per-country items.
curl -X POST 'https://releva.ai/api/v0/products' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json' \ -d '{ "products": [ { "id": "DEMO-1001_en", "groupId": "DEMO-1001", "name": "Linen Summer Shirt", "locale": "en", "currency": "EUR", "listPrice": 39.90, "sku": "DEMO-1001-M", "categories": ["Men/Shirts"], "available": true, "url": "https://demo-store.example.com/products/linen-summer-shirt", "variants": [ { "variantId": "DEMO-1001-M", "sku": "DEMO-1001-M", "barcode": "5901234123457", "listPrice": 39.90, "discountPrice": 29.90, "available": true, "stockQuantity": 12, "imageUrl": "https://demo-store.example.com/images/linen-summer-shirt-m.jpg", "optionValues": [ { "name": "Size", "value": "M" }, { "name": "Color", "value": "White" } ] }, { "variantId": "DEMO-1001-L", "sku": "DEMO-1001-L", "listPrice": 39.90, "available": false, "stockQuantity": 0, "optionValues": [ { "name": "Size", "value": "L" }, { "name": "Color", "value": "White" } ] } ] } ] }'Sending each variant as its own product (older style)
Section titled “Sending each variant as its own product (older style)”The older integration style, one Releva product per variant with the parent product id in a product_id custom field, is still accepted. Use it only if your integration already works this way.
curl -X POST 'https://releva.ai/api/v0/products' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json' \ -d '{ "products": [ { "id": "DEMO-1001-M", "name": "Linen Summer Shirt", "locale": "en", "currency": "EUR", "listPrice": 39.90, "categories": ["Men/Shirts"], "available": true, "url": "https://demo-store.example.com/products/linen-summer-shirt", "imageUrl": "https://demo-store.example.com/images/linen-summer-shirt.jpg", "publishedAt": "2026-05-01T09:00:00Z", "custom": { "string": [ { "key": "product_id", "values": ["DEMO-1001"] }, { "key": "size", "values": ["M"] }, { "key": "color", "values": ["white"] } ] } } ] }'In this style, Delete a product removes one variant at a time, by its own id.
Languages, currencies and markets
Section titled “Languages, currencies and markets”Releva stores one product per id in your shop. Nothing else is part of the key: the same id with another locale overwrites the first version. When you sell one product in several languages or markets, give each version its own id. Releva’s own connectors use:
{yourProductId}_{locale} for example DEMO-1001_en{yourProductId}_{locale}_{market} for example DEMO-1001_en_ukOn every version, set:
localeandcurrency. Left out, they fall back to your shop’s defaults, not to the stored value.groupId, the same on all versions, together withvariants.- For a catalog split by market:
marketHandle,markets, andcanonicalUrlnext to the market’s ownurl.
When the page push carries page.market, product blocks show only products whose marketHandle matches it, and Search As You Type shows products with that marketHandle or with none.
The custom object
Section titled “The custom object”Custom fields are what you filter, group and personalize on: brand, color, material, a promotion end date. They are grouped by value type; each entry is a key with a list of values. No other key is allowed.
| Field | Values | Example |
|---|---|---|
custom.string |
strings | { "key": "color", "values": ["white", "sand"] } |
custom.numeric |
numbers | { "key": "size", "values": [38, 40] } |
custom.date |
dates; a plain 2026-11-01 is accepted |
{ "key": "promoUntil", "values": ["2026-11-01T00:00:00Z"] } |
Releva adds category_level_1, category_level_2 and so on to custom.string from your category paths. Do not send them.
If Product Custom Fields To Sync is set to Specific under Settings › Shop & Integration › Catalog Sync, only the listed custom keys are stored. Other keys are dropped without an error, from API pushes as well as from syncs.
Sending updates
Section titled “Sending updates”Each call updates the products it contains and leaves the rest of your catalog untouched. Within a product, always send the complete object rather than only the fields that changed. A partial product loses data:
| Left out | What happens |
|---|---|
discountPrice |
Cleared. That is how you take a product off sale. |
custom |
Replaced by what you send (only the listed keys when Product Custom Fields To Sync is Specific); left out, the product has no custom fields. |
variants |
Replaced by what you send; left out, the product falls back to one variant built from itself. |
locale, currency |
Reset to your shop’s defaults. |
The required fields must be in every request, even for an update.
Releva compares each price and availability with the stored product. A change is recorded as a catalog event (price drop or rise, back in stock, out of stock), which catalog triggers use. Sending the same payload twice does not trigger a campaign again.
Response
Section titled “Response”202 Accepted with the body {}. The products are queued, not yet stored: they are usually searchable within about 10 seconds. Check them under Data Platform › Products.
Errors
Section titled “Errors”Errors have one shape, { "message": "..." }. When several fields fail, the messages are joined with a space.
| Status | When | Message |
|---|---|---|
400 |
Authentication failed | See Catalog API: Authentication |
400 |
Empty products |
The 'products' field must contain at least 1 items. |
400 |
Numeric id |
The 'products[0].id' field must be a string. |
400 |
Unknown key color on a product |
The object 'products[0]' contains forbidden keys: 'color'. |
400 |
stockQuantity: 1.5 |
The 'products[0].stockQuantity' field must be an integer. |
400 |
locale: "en-US" |
products[0].locale must be a valid ISO-639-1 code! Got en-US instead. |
400 |
currency: "EURO" |
products[0].currency must be a valid ISO-4217 currency code! Got EURO instead. |
400 |
markets: ["de"] |
The 'products[0].markets[0]' field fails to match the required pattern. |
400 |
publishedAt: "2026-05-01" |
products[0].publishedAt must be a valid ISO-8601 date including seconds and timezone offset with optional milliseconds such as 2020-01-01T23:59:59.999Z or 2020-01-01T23:59:59.999-0500 or 2020-01-01T23:59:59-0500. Got 2026-05-01 instead. |
400 |
Relative url |
The 'products[0].url' field must be a valid URL. |
400 |
Variant without variantId |
The 'products[0].variants[0].variantId' field is required. |
402 |
Your shop is disabled | Domain is disabled. Please reach out to support@releva.ai to enable it. |
413 |
Body larger than 800 KB | request entity too large |
500 |
Unexpected error; retry later | An internal error occurred. |
Limits
Section titled “Limits”- Body size: 800 KB per request. Split a large catalog into batches of a few hundred products.
- Rate limits: none.
- Processing: asynchronous, usually within about 10 seconds.