Skip to content

Area: Developers

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.

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.

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.

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 }] }
]
}
]
}'

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.

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 groupId and variants together. Without a non-empty variants, Releva ignores your groupId and uses the product’s own id. With variants but no groupId, the group is the product’s id.
  • A product sent without variants is stored as one variant built from the product itself.
  • The product-level listPrice, discountPrice, available, stockQuantity, sku and imageUrl stay the values Releva shows. Set them to the variant a shopper sees first, usually the first available one.
  • Use the same groupId for every language and market version of one product. The Meta catalog sync uses groupId, variants and markets to 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.

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_uk

On every version, set:

  • locale and currency. Left out, they fall back to your shop’s defaults, not to the stored value.
  • groupId, the same on all versions, together with variants.
  • For a catalog split by market: marketHandle, markets, and canonicalUrl next to the market’s own url.

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.

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.

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.

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