Periodical Product Sync

Updated on October 2, 2024

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:

FieldTypeDescription
idStringThe 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.
nameStringThe product name.
descriptionStringA short description of the product.
localeISO 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.
currencyISO-4217 String (Optional)The currency of this product. If you omit this field, the shop default will be used.
dataObject (Optional)Arbitrary non-searchable product data. Use this to pass through product information that you would like to visualize in recommender results.
listPriceFloatThe regular price of the product.
discountPriceFloatIf the product is on sale, set the discount price here. If not – do not include this field.
categoriesArray[String]Array of category paths where the product is accessible, e.g. ["men/shoes", "men/shoes/hikings", "sports/hiking/shoes"]
availableBooleanTrue if the product is available for sale, false otherwise.
urlStringThe product URL.
imageUrlStringThe URL to the product’s image.
customObject (Optional)The custom fields associated with the product.
publishedAtISO 8601 StringThe date and time when this product was first available for sale.
inventoryArray[Object] (Optional)Product inventory information
inventory[].locationArray[Object] (Optional)Inventory locations in decimal longitude, latitude notation
inventory[].location[].lonFloatinventory location longitude, e.g. 23.5825895
inventory[].location[].latFloatinventory 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}
          ]
        }
      ]
    }
  ]
}