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:
The Data Import Module enabled
An access token with write permissions for products
Create an access token
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>
Request format
Your JSON request must include 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 field mapping object provides flexibility for product fields. Your products can take whatever structure makes sense for your system. The mapping describes how each property in your product data maps to the Fresh Relevance system.
This field mapping functions the same as described in the Import product data article's Field Mapping and Data section.
The only difference in the API is that we accept a source_field_name property instead of an ftp_field_name - these function identically.
Response
The API performs validation on the provided information and returns:
productsRead: The total number of products read from the request (same as the number you sent)
validProducts: The number of products that were successfully queued for import
A successful request returns HTTP status code 202 Accepted.
Processing time
This API only queues products for import. The actual creation/update of products occurs asynchronously after request processing. The time for products to appear depends on the total number being imported, but you should see products start to appear in your Fresh Relevance account within approximately one minute.
To verify imports, go to Data > Products in your Fresh Relevance account.
Limits
There is no fixed limit on the number of products per request, but there is a maximum request content size of approximately 5MB.
When importing large numbers of products, we recommend batching your products into multiple requests.