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.
Authentication
Section titled “Authentication”Send your shop’s secret key as a bearer token:
authorization: Bearer $RELEVA_SECRET_KEYThe 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.
Request format
Section titled “Request format”- 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 get400 {"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.
Responses
Section titled “Responses”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. |
Limits
Section titled “Limits”- 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.
Versioning
Section titled “Versioning”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.