Field Mapping and Data

In order to import any product data into Fresh Relevance we need to be able to understand the source product data items, and be able to map values from the product data's source format to Fresh Relevance's format.

We will explain how to configure your field mappings in this article, using the following example product data:

[
  {
    "id": "ab1234-1",
    "sku": "gzz63774_red_xl_2",
    "price": 19.99,
    "currency": "USD",
    "display_name": "Festive jumper with dancing reindeer",
    "description": "Keep warm and look fashionable this festive season with this warm, stylish and festive jumper. Made in Lapland by elves!",
    "thumbnail": "https://media.example.com/i/gzz63774_red_xl_2/female-red-dancing-reindeer-crop-christmas-jumper",
    "store_link": "https://store.example.com/product/gzz63774_red_xl_2/",
    "stock": 32,
    "color": "red",
    "styles": "Casual|Loose|Generous",
    "categories": "festive|women|jumper|wool",
    "review_id": "0de0fb84-3180-44f6-9bf1-c4dc1b00df46",
    "review_score": 4.9,
    "review_count": 1562,
    "lat": 51.5061984,
    "long": -0.0873022,
    "postcode": "SE19BG",
    "country": "GB",
    "product_locations": "1234|23543"
  },
  {
    "id": "ab1234-3",
    "sku": "izz84994_silver_m_1",
    "price": 14.99,
    "currency": "USD",
    "display_name": "Silver Snowflake Christmas Ornament",
    "description": "Add a touch of elegance to your Christmas tree with this beautifully crafted silver snowflake ornament. Made from high-quality metal, this ornament is sure to become a cherished family keepsake for years to come.",
    "thumbnail": "https://media.example.com/i/izz84994_silver_m_1/silver-snowflake-christmas-ornament",
    "store_link": "https://store.example.com/product/izz84994_silver_m_1/",
    "stock": 60,
    "color": "silver",
    "styles": null,
    "categories": "festive|ornament|decoration",
    "review_id": "44079bfd-57f2-46c2-bf8c-b5d237c7e3cc",
    "review_score": 3.2,
    "review_count": 12,
    "lat": 51.5061984,
    "long": -0.0873022,
    "postcode": "SE19BG",
    "country": "GB",
    "product_locations": "1234|23543"
  },
  {
    "id": "ab1234-4",
    "sku": "jzz95104_blue_s_4",
    "price": 29.99,
    "currency": "USD",
    "display_name": "Plush Santa Claus Stuffed Toy",
    "description": "Bring joy and cheer to your home this Christmas with this adorable plush Santa Claus stuffed toy. Made from soft, high-quality materials, this cuddly toy is perfect for kids and adults alike.",
    "thumbnail": "https://media.example.com/i/jzz95104_blue_s_4/plush-santa-claus-stuffed-toy",
    "store_link": "https://store.example.com/product/jzz95104_blue_s_4/",
    "stock": 25,
    "color": "red",
    "styles": null,
    "categories": "festive|toy|plush",
    "review_id": "fd888119-61ba-423d-84a8-1130ba083d72",
    "review_score": 4.1,
    "review_count": 47,
    "lat": 51.5061984,
    "long": -0.0873022,
    "postcode": "SE19BG",
    "country": "GB",
    "product_locations": "1234|23543"
  }
]

Describing field mappings

In the field_mapping field you need to pass an object with a field for each Fresh Relevance product field you want mapped, with a mapping object defining how values are mapped to it from the source product data.

Almost all field mappings require the source_field_name defining, as this tells importer how to find the unique product identifier for each product item in the source data, the exception to this is fixed value fields, where they will have a val field instead.

Optional fields you can also utilize to define the field mapping are as follows:

We will now look at defining these product field mappings in more detail.

Mandatory field mappings

The absolute minimum amount of fields we require mapping in order to import product data is the prid, but that alone would not be very useful so we highly encourage you to map as many fields as you can.

The mapping for the prid would be as follows:

{
  "prid": {
    "source_field_name": "id"    
  }
}

Optional field mappings

Optional fields you can also utilize are:

Example:

{
  "prid": {
    "source_field_name": "id",
    "field_type": "int"
  },
  "ex.color": {
    "source_field_name": "color"
  },
  "curr": {
    "source_field_name": "currency"
  },
  "uv": {
    "source_field_name": "price",
    "field_type": "double"
  },
  "img": {
    "source_field_name": "thumnail"
  },
  "u": {
    "source_field_name": "store_link"
  },
  "stock": {
    "source_field_name": "stock",
    "field_type": "int"
  },
  "n": {
    "source_field_name": "display_name"
  },
  "cat": {
    "source_field_name": "categories",
    "list_separator": "|"
  }
}

Fixed value fields

Sometimes a element of the required data for Fresh Relevance may not exist in the source product data, but it is a known fixed value. These can be defined using the val field, optionally combined with the field_type field.

{
  "curr": {
    "val": "USD"
  },
  "stock": {
    "val": 1,
    "field_type": "integer"
  }
}

Categories / product tag values

There's special support for uploading categories / tag values for each product. These can be used for many purposes, including in the Recommendation SmartBlock filters to only show products with particular category / tag values.

You can map the categories / tag values to either one CSV (Character Separated Values) style source field or to source multiple fields dependent on your source data format.

🚧

Categories / tags are overwritten

Any existing categories / tag values for the product will be cleared when you upload new categories / tag values to that product!

CSV fields

For mapping to CSV fields you need to map to a single field but specify a list_separator character so we can split the value using this into multiple categories / tags.

{
  "cat": {
    "source_field_name": "categories",
    "list_separator": "|"
  }
}

Multiple fields

For mapping multiple separate fields to categories / tags you need to define a mapping per field using an index suffix on the cat field: cat:{Index}

{
  "cat:1": {
    "source_field_name": "main_category"
  },
  "cat:2": {
    "source_field_name": "secondary_category"
  }
}

Category / tag grouping

You can optionally group category / tag values into groups using the category_group field. For example, suppose you want to pick the style of clothes that a shopper browses most often. You would have a category / tag Group called "Style" and within that, categories such as "casual", "lingerie", "formal". You can import categories / tags into more than one group if required, just add an additional category_group field.

Use the replace_category_group field to replace all existing values in the category / tag group with the imported value.

{
  "cat": {
    "source_field_name": "styles",
    "list_separator": "|",
    "category_group": "style"
  }
}

Google Shopping price fields

Google Shopping product feeds contain compound price and currency value e.g. 14.99 GBP however Fresh Relevance needs the numeric price and currency mapping separately. To do this you can add the field google_currency_field to the indicate that the up and curr field mappings to indicate they refer to a compound price and currency value, and the field value indicates whether we should map the uv (Unit Value) or curr currency code from the source value.

{
  "up": {
    "source_field_name": "google_price",
    "google_currency_field": "uv"
  },
  "curr": {
    "source_field_name": "google_price",
    "google_currency_field": "curr"
  }
}

Promotional flags

We support setting promotional flags on products. These can be used in the recommendation SmartBlock filters to only show products with promotional particular flags. For example, you could use flags for "onOffer", "new" or "blackFriday".

CSV fields

For mapping to CSV fields you need to map to a single field but specify a list_separator character so we can split the value using this into multiple categories / tags.

{
  "promo": {
    "source_field_name": "promotions",
    "list_separator": "|"
  }
}

Multiple fields

For mapping multiple separate fields to promotion flags you need to define a mapping per field using an index suffix on the promo field: promo:{Index}

{
  "promo:1": {
    "source_field_name": "main_promotion"
  },
  "promo:2": {
    "source_field_name": "secondary_promotion"
  }
}

Related products

We support related products , used the related field to indicates which product ids are related to this one. The related products will inherit any Site Brand, Currency and Language that the parent product has. These can then be used by Smartblocks to load these the corresponding full products.

CSV fields

For mapping to CSV fields you need to map to a single field but specify a list_separator character so we can split the value using this into multiple categories / tags.

{
  "related": {
    "source_field_name": "related_ids",
    "list_separator": ","
  }
}

Mapping to variants

To import a variant as a related product use .. to separate the product id from the variant id. For example your source related products CSV might look like:

bbg233,abc123..variantA,abc123..variantB

Product variants

It’s also possible to upload multiple SKU-level variants of the same product. This is done by first including the base product, which is where all the shared data values are stored, then each variant can be included.

You must have a base product record that does not contain a vid field or has a null value, only the variants should have this defined.

A variant is identified by the Variant ID (vid) value and matching Product ID (prid) to the base product. Variant IDs can be any string but must match what is used on your ecommerce site to ensure correlation.

For example if we had this source product data:

[
   {
    "id": "ab1234",
    "sku": "ab1234_red_xl_2",
    "price": 19.99,
    "currency": "USD",
    "display_name": "Festive jumper with dancing reindeer",
    "description": "Keep warm and look fashionable this festive season with this warm, stylish and festive jumper. Made in Lapland by elves!",
    "thumbnail": "https://media.example.com/i/ab1234_red_xl_2",
    "store_link": "https://store.example.com/product/ab1234_red_xl_2/",
    "stock": 32,
    "color": "red",
    "styles": "Casual|Loose|Generous",
    "categories": "festive|women|jumper|wool"
  },
  {
    "id": "ab1234",
    "sku": "ab1234_blue_xl_2",
    "variant": "blue",
    "price": 14.99,
    "currency": "USD",
    "thumbnail": "https://media.example.com/i/ab1234_blue_xl_2",
    "store_link": "https://store.example.com/product/ab1234_blue_xl_2/",
    "stock": 60,
    "color": "blue"
  }  
]

Using this mapping:

{
  "prid": {
    "source_field_name": "id"
  },
  "vid": {
    "source_field_name": "variant"
  },
  "n": {
    "source_field_name": "display_name"
  },
  "img": {
    "source_field_name": "thumbnail"
  },
  "u": {
    "source_field_name": "store_link"
  },
  "curr": {
    "source_field_name": "currency"
  },
  "up": {
    "source_field_name": "price",
    "field_type": "double"
  },
  "stock": {
    "source_field_name": "stock",
    "field_type": "integer"
  }
}

Would create the following product listings, as the blue variant will inherit any omitted fields from the base product:

[
  {
    "prid": "ab1234",
    "vid": null,
    "curr": "USD",
    "n": "Festive jumper with dancing reindeer",
    "img": "https://media.example.com/i/ab1234_red_xl_2",
    "u": "https://store.example.com/product/ab1234_red_xl_2/",
    "uv": 19.99,
    "up": "$19.99",
    "stock": 32
  },
  {
    "prid": "ab1234",
    "vid": "blue",
    "curr": "USD",
    "n": "Festive jumper with dancing reindeer",
    "img": "https://media.example.com/i/ab1234_blue_xl_2",
    "u": "https://store.example.com/product/ab1234_blue_xl_2/",
    "uv": 14.99,
    "up": "£14.99",
    "stock": 60
  }
]

Multiple Price Lists (requires B2B module)

A customer group is a set of prices to allow different pricing by groups, so that you can offer different prices to customers based on their grouping.

For example imagine you had scaled pricing based on a customer loyalty group:

• Base price: £26.99
• Gold Tier: £23.99
• Silver Tier: £24.99
• Bronze Tier: £25.99

You need to ensure these prices are contained within your product data source in this JSON format, with each pricing group defined, the group identifier needs to correlate with your customer records person.cg field :

{

"{Group identifier}": {

"uv": {Numeric price for group},

"ruv": {Original numeric price of product}

}

}

e.g.

[
  {
    "id": "ab1234",
    "sku": "ab1234_red_xl_2",
    "prices": {
      "basePrice": {
        "uv": 26.99
      },
      "goldTier": {
        "uv": 23.99,
        "ruv": 26.99
      },
      "silverTier": {
        "uv": 24.99,
        "ruv": 26.99
      },
      "bronzeTier": {
        "uv": 25.99,
        "ruv": 26.99
      },
    },
    "currency": "USD",
    "display_name": "Festive jumper with dancing reindeer",
    "description": "Keep warm and look fashionable this festive season with this warm, stylish and festive jumper. Made in Lapland by elves!",
    "thumbnail": "https://media.example.com/i/ab1234_red_xl_2",
    "store_link": "https://store.example.com/product/ab1234_red_xl_2/",
    "stock": 32,
    "color": "red",
    "styles": "Casual|Loose|Generous",
    "categories": "festive|women|jumper|wool"
  }
]

These prices are imported into the product catalog using the cg_prices field set to field type jsonpricelist and a corresponding group code is imported to the field person.cg for each customer, to tell the system that that person should see the price for their customer group. e.g.

{
  "cg_prices": {
    "source_field_name": "prices",
    "field_type": "jsonpricelist"
  }
}

Reviews

If using the Social Proof module, it is also possible to import product ratings via a Product Import. This can be useful if Fresh Relevance does not have an integration with your review provider. Before using this feature you should create a Product Review Import channel on the Ratings & Review Providers settings page.

The following fields are used to provide review details for a product:

• rid - Product review ID (rid) field, if neither the product ID or SKU values are suitable for this purpose.
• reviews.rating - The average review rating for a product
• reviews.ratingCount - The number of reviews collected

Below is an example of how to setup the field mapping to import product ratings:

{
  "rid": {
    "source_field_name": "review_id"
  },
  "reviews.rating": {
    "source_field_name": "review_score",
    "field_type": "double"
  },
  "reviews.ratingCount": {
    "source_field_name": "review_count",
    "field_type": "int"
  }
}

Product recommendations filtering

📘

Before adding custom data for product recommendation filtering

You must review the documentation on filtering before designing data structures to upload for filtering Product Recommendations.

We recommend using one of the following types of data when uploading for product recommendation filtering:

• Tag values and tag groups
• Promotion flags
• Site brands
• Price
• Product ID
• Stock level
• Language

If you need to upload custom fields for product filtering, contact your Account Manager or client support to discuss your requirements.

Location information

For products that are location centric such as a track day, spa session etc... you can attach location information to a product. This can take the form of a latitude and longitude, or a country code and postal code. When using postcodes they are automatically resolved to a latitude and longitude and attached to the product.

You can specify one or more locations for a product. When we need to filter by location Fresh Relevance will find the nearest location within the locations; and optionally you can specify a maximum distance in metres.

Te following fields should be used within an object called location_ids to provide location details for a product:

• location_type - The type of location information, one of:
  • latlng - Using a latitude and longitude.
  • postcode - Using postcode / zip code.
  • None specified - If directly setting location IDs during a product import without resolving from a latitude/longitude or a postal code.
• For location type latlng only:
  • latitude_field_name - The field name holding the latitude coordinates.
  • longitude_field_name - The field name holding the longitude coordinates.
• For location type postcode only:
  • postcode_field_name - The field name holding the postcode / zip code.
  • country_code_field_name - The country code for the postcode; must be a 2 letter upper case ISO 3166-1 Alpha-2 country code (for example, GB, FR, US, AU).
• Optional parameters:
  • location_sets - Which location sets to resolve to, note mystores, and uk-cities system are automatically provided sets.
  • list_separator - What separator character you are using to separate values in the location_sets value.
  • max_distance - What is the maximum distance to consider a nearest location in metres.

Here are some examples of how to create mappings for each location type:

{
  "location_ids": {
    "latitude_field_name": "lat",
    "longitude_field_name": "long",
    "location_type": "latlng",
    "location_sets": "mystores|template:uk-cities",
    "list_separator": "|",
    "max_distance": 10000
  }
}

{
  "location_ids": {
    "postcode_field_name": "postcode",
    "country_code_field_name": "country",
    "location_type": "postcode",
    "location_sets": "mystores|template:uk-cities",
    "list_separator": "|"
  }
}

{
  "location_ids": {
    "source_field_name": "product_locations",
    "list_separator": "|"
  }
}