This API is in active development. Provide any feedback or issues encountered to the Fresh Relevance team.

Authentication

To use the product import API, you need to have the Data Import Module and create an access token with write permissions for products.

To do this in your Fresh Relevance account:

Expand the User menu, and go to Settings > Other Integrations > Fresh Relevance Access Tokens.
Expand the Create Token drop-down menu, then enter a name and optionally an expiry date.
Expand the Token type drop-down menu and choose API Key.
In the Write column, select the products permission checkbox.
Select Create Token and the token is displayed.

Import products

POST https://api.freshrelevance.com/api/<website_id>/products/import/

<website_id> uniquely identifies your Fresh Relevance account.

The following HTTP headers should be provided:

Content-Type: application/json
Accept: application/json
X-API-KEY: <access token generated above>

The JSON request must provide two fields:

products - an array of product record data.
field_mapping - an object describing how fields in the products records map to Fresh Relevance data
- See the Field mapping section below.

An example request:

{
  "products": [
    {
      "prid": "10001",
      "name": "Product API Test Product 1",
      "curr": "EUR",
      "desc": "Automatically generated product for product API testing",
      "unit_value": 9364.64,
      "unit_value_currency": "\u00a39364.64",
      "stock": 0,
      "country": "be",
      "created": 1675165286,
      "property3": 1,
      "property1": "green",
      "property4": false
    },
    {
      "prid": "10002",
      "name": "Product API Test Product 2",
      "curr": "EUR",
      "desc": "Automatically generated product for product API testing",
      "unit_value": 3603.28,
      "unit_value_currency": "\u00a33603.28",
      "stock": 3,
      "country": "nl",
      "created": 1672569393,
      "property2": "small",
      "property1": "blue"
    }
  ],
  "field_mapping": {
    "sbr": {
      "source_field_name": "country"
    },
    "lang": {
      "source_field_name": "country"
    },
    "curr": {
      "source_field_name": "curr"
    },
    "prid": {
      "source_field_name": "prid"
    },
    "n": {
      "source_field_name": "name"
    },
    "desc": {
      "source_field_name": "desc"
    },
    "stock": {
      "source_field_name": "stock"
    },
    "uv": {
      "source_field_name": "unit_value"
    },
    "up": {
      "source_field_name": "unit_value_currency"
    },
    "ex.created": {
      "source_field_name": "created",
      "field_type": "datetime"
    },
    "ex.property1": {
      "source_field_name": "property1"
    },
    "ex.property2": {
      "source_field_name": "property2"
    },
    "ex.property3": {
      "source_field_name": "property3"
    },
    "ex.property4": {
      "source_field_name": "property4"
    },
    "ex.property5": {
      "source_field_name": "property5"
    },
    "cat:property1": {
      "source_field_name": "property1",
      "category_group": "p1",
      "replace_category_group": true
    },
    "cat:property2": {
      "source_field_name": "property2",
      "category_group": "p2",
      "replace_category_group": true
    },
    "cat:property3": {
      "source_field_name": "property3",
      "category_group": "p3",
      "replace_category_group": true
    },
    "cat:property4": {
      "source_field_name": "property4",
      "category_group": "p4",
      "replace_category_group": true
    },
    "cat:property5": {
      "source_field_name": "property5",
      "category_group": "p5",
      "replace_category_group": true
    }
  }
}

Field mapping

A separate field mapping object allows flexibility for the products fields themselves. Products can take whatever form makes sense from your system. The mapping describes how each property in product data maps in to the Fresh Relevance system.

This field mapping behaves the same as is described in the Field Mapping and Data section in Import product data.

The only difference in the API is that we accept a source_field_name property instead of an ftp_field_name - these function identically.

Results

The API call above performs validation on the provided information and returns the following fields:

productsRead - the total number of products read from the request.
- This is the same amount that you sent.
validProducts - the number of products that could be queued for import.

An HTTP 202 Accepted is returned on success.

This API only queues the products for import. The actual creation/update of products occurs asynchronously after the request has been processed. The actual time for products to be updated depends on the number of products being imported, but you should see products start to appear in your Fresh Relevance account within a minute or so.

To check this, go to Data > Products.

Limits

There is no fixed limit on the number of products that can be imported per request, however there is a max request content size of around 5MB.

When importing large numbers of products, we recommend batching up your products and sending multiple requests.

Mobile and app API

Import product data

Import review data

Single page application hooks

Integration API