Periodical Product Sync

The product Sync API is an API that you need to develop in your shop so that Releva can periodically sync its internal catalogue with your shop catalogue.

Do I need to develop it?

This is basically a catch-all mechanism which will ensure that any changes to your catalogue are reflected in Releva even if your tracking integration does not work as expected and you miss calling the product update API for some of your catalog changes. Although it’s not required for the functioning of Releva, we highly recommend that you implement it to limit situations where Releva’s version of your catalogue is stale.

Request Format

Releva will perform the following curl equivalent:

curl -H 'authorization: Bearer <secretKey>' -H 'x-rlv-authorization: Bearer <secretKey>' -H 'Content-Type: application/json' -XGET https://your-awesome-shop.com/api/releva/products?page=N

Note that we send both the standard authorization header and the non-standard x-rlv-authorization header and they contain the same value. This is due to the fact that in a standard PHP and Apache setup, Apache does not forward the authorization headers to PHP unless specifically told to do so. This has proven to be a challenge for some of our customers.

Response Format

Releva will expect you to provide a JSON response with HTTP status 200 and the following structure. Your response should contain 20-50 products.

{
  "pageCount": 123,
  "products": [
    {
      "id": "...",
      "name": "...",
      "description": "...",
      "locale": "en",
      "currency": "BGN",
      "categories": [
        "Clothes/Shirts"
      ],
      "url": "...",
      "imageUrl": "...",
      "publishedAt": "2020-04-15T03:21:50+00:00",
      "custom": {
        "string": [
          {
            "key": "Season",
            "values": [
              "Summer"
            ]
          },
          {
            "key": "Gender",
            "values": [
              "F"
            ]
          },
          {
            "key": "Size",
            "values": [
              "L"
            ]
          }
        ]
      },
      "available": true,
      "listPrice": 169,
      "discountPrice": 126.75,
      "inventory": [
        {
          "location": [
             {"lat": 39.9352959, "lon": 23.5825895}
          ]
        }
      ]
    }
  ]
}

If a product id in the request is not in your catalogue, it should not be included in the response.

The products Array

Each element in this array should have the following structure:

Field	Type	Description
id	String	The product id. It should match the id that you pass as product.id and cart.products[].id in the frontend integration, as well as in carts[].products[].id in the backend integration. If your shop has multiple lagnauges, the product id should be unique across 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 currency of this product. 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	String	The product URL.
imageUrl	String	The URL to the product’s image.
custom	Object (Optional)	The custom fields associated with the product.
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

What if I don’t know the total number of pages or cannot fetch results for a given page?

We also support cursor-based pagination as an alternative in case your backend does not support traditional pagination. In this case, Releva will perform the following request:

curl -H 'authorization: Bearer <secretKey>' -H 'Content-Type: application/json' -XGET https://your-awesome-shop.com/api/releva/products?cursor=.,,

You should then return a subset of products, and the nextCursor string which Releva will use to fetch the next batch. When there are no more results, please return a nextCursor with the value of null.

{
  "nextCursor": "...",
  "products": [
    {
      "id": "...",
      "name": "...",
      "description": "...",
      "locale": "en",
      "currency": "BGN",
      "categories": [
        "Clothes/Shirts"
      ],
      "url": "...",
      "imageUrl": "...",
      "publishedAt": "2020-04-15T03:21:50+00:00",
      "custom": {
        "string": [
          {
            "key": "Season",
            "values": [
              "Summer"
            ]
          },
          {
            "key": "Gender",
            "values": [
              "F"
            ]
          },
          {
            "key": "Size",
            "values": [
              "L"
            ]
          }
        ]
      },
      "available": true,
      "listPrice": 169,
      "discountPrice": 126.75,
      "inventory": [
        {
          "location": [
             {"lat": 39.9352959, "lon": 23.5825895}
          ]
        }
      ]
    }
  ]
}