Skip to content

Area: Developers

POST

Create or update products

Path
/products
Auth
Secret key · server only
POST
/products
curl --request POST \
--url https://releva.ai/api/v0/products \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "products": [ { "id": "DEMO-1001", "name": "Linen Summer Shirt", "locale": "en", "currency": "EUR", "listPrice": 39.9, "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" } ] }'

Creates or updates products in the catalog of the domain that owns the secret key. A product is identified by its id within the domain only (locale and market are not part of the key), so each language or market version needs its own id. Processing is asynchronous: a 202 means the products were queued. They are usually searchable within about 10 seconds. Omitted optional fields keep their stored value, except discountPrice (cleared), custom and variants (replaced), and locale/currency (reset to the domain default).

Media typeapplication/json
object
products
required
Array<object>
>= 1 items
object
id
required

Unique within the domain across all locales and markets.

string
name
required
string
description
string
currency

ISO-4217 currency code. Defaults to the domain currency.

string
listPrice
required
number
discountPrice

Sale price. Omit when not on sale; omitting it clears a stored value. Should be lower than listPrice (not enforced).

number
stockQuantity
integer
categories
required

Category paths separated by /, e.g. Men/Shirts. May be empty.

Array<string>
publishedAt

ISO-8601 date-time with seconds and timezone offset, optional milliseconds (max 3 digits).

string
/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?(Z|[+-]\d{2}:?\d{2})$/
locale

ISO-639-1 two-letter language code. Defaults to the domain locale.

string
/^[a-z]{2}$/
marketHandle

Your identifier for the market this product document belongs to.

string
markets

ISO-3166-1 alpha-2 country codes, upper case.

Array<string>
data

Arbitrary non-searchable data returned with recommendations.

object
available
required
boolean
url
string format: uri
canonicalUrl

Canonical URL without locale or market prefix. Falls back to url.

string format: uri
imageUrl

Defaults to the domain’s default product image.

string format: uri
sku
string
inventory
Array<object>
object
location
Array<object>
object
lon
required
number
lat
required
number
groupId

Shared id of all documents of one product. Only used together with a non-empty variants array.

string
variants

Replaced on every write. When omitted, one variant is created from the product fields.

Array<object>
object
variantId
required
string
sku
string
listPrice
number
discountPrice
number
available
boolean
stockQuantity
integer
imageUrl
string format: uri
barcode
string
optionValues
Array<object>
object
name
required
string
value
required
string
custom

Replaced on every write. Category levels (category_level_N) are added automatically.

object
string
Array<object>
object
key
required
string
values
required
Array<string>
numeric
Array<object>
object
key
required
string
values
required
Array<number>
date
Array<object>
object
key
required
string
values
required
Array<string>
deleteMissingVariants

Accepted for backwards compatibility. Has no effect.

boolean

Example

{
"products": [
{
"id": "DEMO-1001",
"name": "Linen Summer Shirt",
"locale": "en",
"currency": "EUR",
"listPrice": 39.9,
"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"
}
]
}

Accepted for asynchronous processing.

Media typeapplication/json
object
0

Example

{}

Authentication or validation error.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Examples

{
"message": "Authorization header is missing."
}

The domain is disabled.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "Domain is disabled. Please reach out to support@releva.ai to enable it."
}

Request body larger than 800 KB.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "request entity too large"
}

Unexpected server error.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "An internal error occurred."
}