The Product Update API #
The product update API allows you to send bulk catalog updates to Releva. Any catalog updates submitted through this API will be live within 10 seconds of receiving a successful response.
Do I need to call it? #
Yes, you need to call it whenever changes occur in your catalog – for example when a product (or products) becomes out of stock, or in stock, or the price changes. This is the primary method Releva uses to learn about changes in your catalogue.
Request Parameters #
You may perform requests to the API using the following curl equivalent:
curl -H 'Content-Type: application/json' -H 'Authorization: Bearer <secretKey>' -XPOST https://releva.ai/api/v0/products -d'{
"products": [
{
"id": "productId1",
"name": "Test Product",
"description": "Some Description",
"locale": "en",
"currency": "USD",
"listPrice": 12.5,
"discountPrice": 10.99,
"categories": [
"men/shoes/hiking"
],
"available": true,
"url": "https://my-awesome-shop/products/productId1",
"imageUrl": "https://cdn.my-awesome-shop/products/productId1_img1.png",
"publishedAt": "2019-06-19T23:45:56",
"custom": {
"string": [
{"key": "color", "values": ["red", "blue"]}
],
"numeric": [
{"key": "size", "values": [14, 15, 18]}
],
"date": [
{"key": "in_promo_until", "values": ["2022-11-01T00:00:00.000Z"]}
]
},
"inventory": [
{
"location": [
{"lat": 39.9352959, "lon": 23.5825895}
]
}
]
}
]
}'What if my products have variants and each variant has a different URL? #
If you sell multi-variant products, you need to send them as individual products to Releva, and the id field which you pass to Releva should be based on the variant id in your catalogue.
In addition, you need to pass product_id (this should be id of the product this variant belongs to) custom field as part of the API call as well as any other attributes (e.g. size, color, etc.) that are specific to a variant. Here is an example:
curl -H 'Content-Type: application/json' -H 'Authorization: Bearer <secretKey>' -XPOST https://releva.ai/api/v0/products -d'{
"deleteMissingVariants": false,
"products": [
{
"id": "variantId1",
"name": "Test Product",
"description": "Some Description",
"locale": "en",
"currency": "USD",
"listPrice": 12.5,
"discountPrice": 10.99,
"categories": [
"men/shoes/hiking"
],
"available": true,
"url": "https://my-awesome-shop/products/productId1",
"imageUrl": "https://cdn.my-awesome-shop/products/productId1_img1.png",
"publishedAt": "2019-06-19T23:45:56",
"custom": {
"string": [
{"key": "product_id", "values": ["productId1"]},
{"key": "size", "values": ["S"]},
{"key": "color", "values": ["red"]}
]
}
},
{
"id": "variantId2",
"name": "Test Product",
"description": "Some Description",
"locale": "en",
"currency": "USD",
"listPrice": 10.5,
"discountPrice": 8.99,
"categories": [
"men/shoes/hiking"
],
"available": true,
"url": "https://my-awesome-shop/products/productId1",
"imageUrl": "https://cdn.my-awesome-shop/products/productId1_img1.png",
"publishedAt": "2019-06-19T23:45:56",
"custom": {
"string": [
{"key": "product_id", "values": ["productId1"]},
{"key": "size", "values": ["L"]},
{"key": "color", "values": ["blue"]}
]
}
}
]
}'Note: Setting deleteMissingVariants to true activates a special cleanup logic – for each product_id in the current API call, we will delete all variants which are not part of the products list in the request body. Only use this option if you cannot implement the regular Product Delete mechanism.
The products Array #
This object is an array of Objects with the following properties.
| Field | Type | Description |
|---|---|---|
| id | String | A unique product ID identifying your product. Note that if you have a multi-locale shop ( you sell in multiple languages / currencies), this id will need to be unique across all locales. |
| name | String | The product name. |
| description | String | A short description of the product. |
| locale | ISO-639-1 String (Optional) | If you sell in multiple languages or currencies, set this to the current locale. If you omit this field, the shop default will be used. |
| currency | ISO-4217 String (Optional) | The product currency. If you omit this field, the shop default will be used. |
| data | Object (Optional) | Arbitrary non-searchable product data. Use this to pass through product information that you would like to visualize in recommender results. |
| listPrice | Float | The regular price of the product. |
| discountPrice | Float | If the product is on sale, set the discount price here. If not do not include this field. |
| categories | Array[String] | Array of category paths where the product is accessible, e.g. ["men/shoes", "men/shoes/hikings", "sports/hiking/shoes"] |
| available | Boolean | True if the product is available for sale, false otherwise. |
| url | Absolute URL String | The product URL. |
| imageUrl | Absolute URL String | The URL to the product’s image. |
| custom | Object (Optional) | The custom fields associated with the currently viewed product, for example the available sizes. |
| publishedAt | ISO-8601 String | The date and time when this product was first available for sale. |
| inventory | Array[Object] (Optional) | Product inventory information |
| inventory[].location | Array[Object] (Optional) | Inventory locations in decimal longitude, latitude notation |
| inventory[].location[].lon | Float | inventory location longitude, e.g. 23.5825895 |
| inventory[].location[].lat | Float | inventory location latitude, e.g. 39.9352959 |
Response Format #
A successful response will return HTTP Status 202 with an empty response body ({}).
An error response will return a HTTP 4xx or 5xx status code and have the following structure:
{
"message": "A description of the error and how to fix it, if it's a client error."
}