Skip to content

Area: Developers

Catalog API overview

Used byCustom website, Shopify, WooCommerce, Magento 2, Magento 1, PrestaShop, OpenCart, CloudCart, CS-Cart, GombaShop, MerchantPro, Partner platforms, Mobile SDKs

The catalog API creates, updates, deletes and resyncs the products of one shop. Each call has its own page:

Call Endpoint What it does
Create or update products POST /products Send new and changed products, with variants, languages and markets
Update product availability POST /products/availability Change only available on existing products
Delete a product DELETE /products/{id} Remove one product for good
Let Releva pull your catalog your endpoint, and POST /products/sync The endpoint Releva reads in a full sync, and the call that starts one

All endpoints are under https://releva.ai/api/v0. For how these fit together, read How your catalog gets into Releva. The generated field-by-field reference for each endpoint lives in the API reference.

Send your shop’s secret key as a bearer token:

authorization: Bearer $RELEVA_SECRET_KEY

The key is a UUID and identifies the shop (domain). Everything you send applies to that shop; there is no shop id in the body. Find the key in the Releva admin under Settings › Shop & Integration.

Authentication failures answer 400, not 401:

Problem Message
No authorization header Authorization header is missing.
Header is not Bearer <token> Authorization header is malformed. It should look like `Bearer <string>`.
Token is not a UUID Authorization header contains an invalid Bearer token.
No shop has this key Domain with the provided secret key cannot be found.

A shop that has been switched off answers 402 with Domain is disabled. Please reach out to support@releva.ai to enable it.

  • HTTPS only. Plain HTTP answers 400 {"message":"We do not support non-HTTPS requests."}.
  • Send JSON with content-type: application/json. With any other content type the body is not parsed and you get 400 {"message":"The '' field is required."}.
  • Bodies are limited to 800 KB. Larger bodies answer 413 {"message":"request entity too large"}. There is no maximum number of products per request other than that limit. Split large catalogs into batches of a few hundred products.
  • Product objects are validated strictly: any key that is not in the schema is rejected.

Every successful call answers 202 Accepted with the body {}. Processing is asynchronous; the change is visible a few seconds later. See Writes are asynchronous.

Errors have one shape:

{ "message": "The 'products[0].listPrice' field must be a number. The 'products[0].categories' field is required." }

There is no error code or field property. When several fields fail validation, the messages are joined with a space.

Status When
202 Accepted and queued
400 Authentication failed, validation failed, or the body could not be parsed
402 The shop is disabled
413 Body larger than 800 KB
500 Unexpected error. The body is {"message":"An internal error occurred."}. Retry later.
  • Body size: 800 KB per request.
  • Rate limits: none on the catalog endpoints. Be reasonable; one request per product change or batches of a few hundred products are both fine.
  • Processing: one queued write per product. Ingestion is usually complete within about 10 seconds.

All catalog endpoints are under /api/v0. Changes are listed in the API changelog. Unknown fields are rejected, so new fields are safe to add only after they appear in the reference.