Skip to content

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 ​

MethodPathPurpose
GET/api/2026-04/productsList synchronized products.
POST/api/2026-04/productsCreate 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}/reviewsList 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.

bash
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:

json
{
  "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:

FieldRequiredDescription
langYesProduct language code.
nameYesProduct name in that language.
descriptionNoFull product description.
description_shortNoShort product description.
urlNoPublic product URL.
photo_urlNoProduct 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, send variants: [] and optionally the product sku.
  • For kind: variable, send the complete variants array. An empty array clears the stored variants. Each entry requires an id and an options array, and can include a sku. Each option requires a name and a value.
  • 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:

FilterDescription
pagePage number, starting at 1.
per_pagePage size, from 1 to 100. Default is 25.
searchSearches localized product names.
has_reviewsBoolean. true returns products with reviews; false returns products without reviews.
sortcreated_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:

FilterDescription
pagePage number, starting at 1.
per_pagePage size, from 1 to 100. Default is 25.
ratingExact rating match.
sortdate_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.

Public API documentation for Revi.