Products Guide
In 2026-04, product writes and order-product attachments can return 403 connection_unavailable if the connection is disabled, retired or removed during the request. Check the connection before retrying. Earlier items in a bulk product write remain stored; an order-product attachment request rolls back its transaction if the connection check fails.
Products allow Revi to request, organize, and display product reviews. Product IDs are external IDs from your commerce platform.
Endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /api/2026-04/products | List synchronized products. |
POST | /api/2026-04/products | Create or update products in bulk. |
GET | /api/2026-04/products/{id_product} | Read one product by external product ID. |
GET | /api/2026-04/products/{id_product}/reviews | List reviews for one product. |
Create Or Update Products
Each product requires id_product with 36 characters or fewer. Send locale entries when product names or URLs differ by language.
Preserve complete language codes in both lang and locale[].lang. In particular, pt-BR and zh-Hant are distinct from pt and zh. Revi normalizes pt_BR to pt-BR and zh_TW to zh-Hant when those codes are available. Resolution may fall back to an available base-language code, or to the business default language if no candidate is available. Use the code returned by Revi in subsequent reads.
Supported top-level input fields are id_product, lang, name, description, description_short, url, photo_url, images, price, currency, stock, allow_out_of_stock_orders, ean, sku, upc, jan, isbn, mpn, brand, locale, combinations, and catalog_variants.
images is an optional ordered gallery of catalog images for the product, shared across its languages. Send public HTTP(S) URLs, with the cover first and no more than ten entries; product gallery widgets display up to three. Omit the field to preserve the stored gallery, or send [] to clear it. A supplied list replaces the gallery; duplicate and invalid URLs are discarded. Each URL can contain at most 2048 characters. These are product catalog images, not customer-uploaded photos. Keep sending photo_url for the product's primary image. Gallery URLs are not added to product GET responses.
curl "https://api.revi.io/api/2026-04/products" \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-API-KEY: revi_test_xxxxxxxxx" \
-d '{
"products": [
{
"id_product": "sku-123",
"price": "29.90",
"currency": "EUR",
"stock": 20,
"ean": "8430000000000",
"sku": "RUN-RED-42",
"brand": "ExampleBrand",
"locale": [
{
"lang": "en",
"name": "Running shoe",
"description": "Lightweight running shoe.",
"url": "https://example.com/products/running-shoe",
"photo_url": "https://example.com/images/running-shoe.jpg"
}
],
"combinations": [
{
"id_combination": "sku-123-red-42",
"sku": "RUN-RED-42",
"photo_url": "https://example.com/images/running-shoe-red.jpg"
}
]
}
]
}'Batch responses include one result per product:
{
"success": true,
"data": {
"products_count": 1,
"results": [
{
"id_product": "sku-123",
"success": true
}
]
},
"meta": {
"api_version": "2026-04"
}
}If all rows fail validation or processing, the API returns 422 with the per-row results inside error.details.
Locales
Each locale item requires:
| Field | Required | Description |
|---|---|---|
lang | Yes | Product language code. |
name | Yes | Product name in that language. |
description | No | Full product description. |
description_short | No | Short product description. |
url | No | Public product URL. |
photo_url | No | Product image URL. |
Combinations
Use combinations for variants. Each combination requires id_combination with 50 characters or fewer.
Supported combination fields include ean, sku, upc, jan, isbn, mpn, brand, and photo_url.
Catalog Variants
Send an optional catalog_variants object to replace the complete variant snapshot for a product in its store. This field is accepted by POST /api/2026-04/products and POST /api/2026-10/stores/{store_id}/products. Omit it for partial updates to preserve the stored snapshot. Product responses omit this write-only field.
- For
kind: simple, sendvariants: []and optionally the productsku. - For
kind: variable, send the completevariantsarray. An empty array clears the stored variants. Each entry requires anidand anoptionsarray, and can include asku. Each option requires anameand avalue. - Variant IDs and option names within a variant must be unique after trimming and without regard to case. A variant supports up to 12 options. The normalized snapshot must fit in 1 MiB. Use at most 2,048 variants in 2026-04 or 100 in 2026-10. In 2026-10 each variant counts as one item toward the write workload limit.
List Products
Supported filters:
| Filter | Description |
|---|---|
page | Page number, starting at 1. |
per_page | Page size, from 1 to 100. Default is 25. |
search | Searches localized product names. |
has_reviews | Boolean. true returns products with reviews; false returns products without reviews. |
sort | created_desc, rating_desc, rating_asc, or reviews_desc. |
Product list responses return compact catalog rows: id_product, id_store, avg_rating, num_reviews, ean, sku, brand, price, and stock.
Read One Product
GET /api/2026-04/products/{id_product} returns the compact product fields plus locale entries and combinations. Locale entries include lang, name, description, url, and photo_url. Combination entries include id_combination, ean, sku, upc, brand, and photo_url.
Product Reviews
Use GET /api/2026-04/products/{id_product}/reviews to fetch reviews for one product.
Supported filters:
| Filter | Description |
|---|---|
page | Page number, starting at 1. |
per_page | Page size, from 1 to 100. Default is 25. |
rating | Exact rating match. |
sort | date_desc or date_asc. |
Product review rows returned from this endpoint are intentionally smaller than global review rows. They include id, id_order, customer_name, customer_lastname, comment, rating, lang, and date.