Catalog format & requirements

Definition

A product catalog represents the entire collection of products that are available for purchase on an e-commerce store.

Each catalog item is represented as a JSON object with the following structure:

{
  "id": "805371A",
  "itemGroupId": "805371",
  "categoryHierarchies": [
    { "categories": ["Women", "Shoes"] },
    { "categories": ["Sports & Fitness", "Shoes"] }
  ],
  "title": "Red Shoes",
  "description": "Fancy red shoes",
  "brand": "Designer Brand",
  "languageCode": "en",
  "productMetadata": {
    "stockState": "IN_STOCK",
    "availableQuantity": 30,
    "exactPrice": {
      "originalPrice": 119.99,
      "displayPrice": 89.99
    },
    "currencyCode": "USD",
    "canonicalProductUri": "https://www.store.com/shoes/red-shoes",
    "images": [
      {
        "uri": "https://www.store.com/images/805371.jpg",
        "width": 500,
        "height": 500
      }
    ]
  }
}

Note: The above example includes line-breaks for readability, however the catalog file you create must include one JSON encoded catalog item per line. The file must also be encoded in UTF-8.

{"id":"805371","categoryHierarchies":[{"categories":["Women","Shoes"]}],"title":"Red Shoes","description":"Fancy red shoes","languageCode":"en","productMetadata":{"exactPrice":{"originalPrice":119.99,"displayPrice":89.99},"currencyCode":"USD","canonicalProductUri":"https://www.store.com/shoes/red-shoes","images":[{"uri":"https://www.store.com/images/805371.jpg","width":500,"height":500}]}}
{"id":"805372","categoryHierarchies":[{"categories":["Women","Shoes"]}],"title":"Green Shoes","description":"Fancy green shoes","languageCode":"en","productMetadata":{"exactPrice":{"originalPrice":148.99,"displayPrice":129.99},"currencyCode":"USD","canonicalProductUri":"https://www.store.com/shoes/green-shoes","images":[{"uri":"https://www.store.com/images/805372.jpg","width":500,"height":500}]}}

Properties

id

  • Type: String

  • Required

  • Maximum size: 128 bytes

This ID must be unique among all catalog items within the same catalog. It must be the same ID that is tracked with product page views in your Fanplayr integration.

itemGroupId

  • Type: String

  • Required (depending on catalog level configuration)

  • Maximum size: 128 bytes

Product variant group identifier, also known as the "master" product identifier. This links all related product variants together for prediction results.

Either all of your catalog items must have a value for itemGroupId or none of them can. You cannot import catalog data with itemGroupId set for some items but not for others. This field is required when using the Master/Master or Variant/Master catalog level.

categoryHierarchies

  • Type: Array

  • Required (at least one category hierarchy entry is required)

  • Maximum size: 1000 bytes (when encoded as JSON)

Catalog item categories. This field is repeated for supporting one catalog item belonging to several parallel category hierarchies. At least one category must be present.

For example, if a shoes product belongs to both Women > Shoes and Sports & Fitness > Shoes, it could be represented as:

"categoryHierarchies": [
  { "categories": ["Women", "Shoes"] },
  { "categories": ["Sports & Fitness", "Shoes"] }
]

title

  • Type: String

  • Required

  • Maximum size: 500 bytes

Catalog item title.

description

  • Type: String

  • Maximum size: 500 bytes

Catalog item description. This value cannot be displayed in widgets but it can help improve the recommendation model.

brand

  • Type: String

  • Maximum size: 100 bytes

The brand or manufacturer associated with the product.

languageCode

  • Type: String

  • Required

The language of the title/description. Use language tags defined by BCP 47. https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Our supported language codes include "en", "es", "fr", "de", "ar", "fa", "zh", "ja", "ko", "sv", "ro", "nl".

stockState

  • Type: ENUM

  • Nested under: productMetadata

  • Required

Must be equal to one of the following values:

  • IN_STOCK - Item in stock.

  • OUT_OF_STOCK - Item out of stock.

  • PREORDER - Item that is in pre-order state.

  • BACKORDER - Item that is back-ordered (i.e. temporarily out of stock).

availableQuantity

  • Type: Number

  • Nested under: productMetadata

The remaining quantity of the item that is available for purchase.

originalPrice

  • Type: Float

  • Nested under: productMetadata.exactPrice

  • Required

The base price of the catalog item.

currencyCode

  • Type: String

  • Required

The currency code for the item prices. Use three-character ISO-4217 code.

images

  • Type: Array

  • Required (at least one image is required)

An array of product images. Only the first image is displayed in the Recommendation component. At least one image is required.

Each image should be an object with the following structure:

{
  // Required. URL of the image.
  // Maximum size: 1000 bytes
  "uri": "https://www.store.com/images/805371.jpg",
  // Optional. Image width in pixels.
  "width": 500,
  // Optional. Image height in pixels.
  "height": 500
}

tags

  • Type: Array of String

  • Maximum size: 500 bytes (combined)

Optional tags to associate with the catalog item. Each should be a UTF-8 encoded string. The total length of all tags for a single catalog item must not exceed 500 bytes.

itemAttributes

  • Type: Object

  • Maximum size: 1000 bytes (combined)

Optional. Extra item attributes to be included in the recommendation model. For example, for retail products this could include the product style, color, etc. These attributes can add additional signals for recommendation models.

Item attributes should be divided into categorical and numerical sets with the following structure:

"itemAttributes": {
  "categoricalFeatures": {
    "colors": {
      "value": ["red", "blue"]
    },
    "sizes": {
      "value": ["S", "M", "L"]
    }
  },
  "numericalFeatures": {
    "lengths_cm": {
      "value": [2.3, 15.4]
    },
    "heights_cm": {
      "value":[8.1, 6.4]
    }
  }
}

Catalog file format

The product catalog file format has the following requirements:

  • Each catalog item must be formatted using the JSON structure described above.

  • Each catalog item must contained on a single line.

  • The total size of the catalog file should be no more than 50 MB uncompressed. If your catalog exceeds the size, you can split it and import it multiple times.

  • All items must use the same language and currency. It is not possible to mix different languages and currencies in the same catalog due to limitations when training AI models. You will need to manage separate catalogs and projects if your e-commerce store contains multiple store views with different languages and/or currencies.

The following is an example of a catalog file with 2 items:

{"id":"PRODUCT_1","categoryHierarchies":[{"categories":["Women","Shoes"]},{"categories":["Sports & Fitness","Shoes"]}],"title":"Red Shoes","description":"Fancy red shoes","languageCode":"en","productMetadata":{"stockState":"IN_STOCK","availableQuantity":30,"exactPrice":{"originalPrice":119.99},"currencyCode":"USD","canonicalProductUri":"https://www.store.com/shoes/red-shoes","images":[{"uri":"https://www.store.com/images/PRODUCT_1.jpg","width":500,"height":500}]}}
{"id":"PRODUCT_2","categoryHierarchies":[{"categories":["Men","Shoes"]},{"categories":["Sports & Fitness","Shoes"]}],"title":"Blue Shoes","description":"Fast blue shoes","languageCode":"en","productMetadata":{"stockState":"IN_STOCK","availableQuantity":17,"exactPrice":{"originalPrice":119.99},"currencyCode":"USD","canonicalProductUri":"https://www.store.com/shoes/blue-shoes","images":[{"uri":"https://www.store.com/images/PRODUCT_2.jpg","width":500,"height":500}]}}

Catalog levels

Before importing your catalog for the first time, you must determine whether you are wish to track master items or variants with your user events on site, and whether you want master items or variants returned with your predictions. Fanplayr will assist in configuring your integration.

Master items represent a group of similar items (in other words, a SKU group). An example of a master item might be "V-neck shirt", with variants such as "Brown v-neck shirt, size XL" and "White v-neck shirt, size S". Masters and variants are sometimes described as "parent" and "child" items.

The possible combinations for the Catalog Level are:

  • Variant/Variant: Capture variants with user events and return variants with predictions.

  • Master/Master: Capture master items with user events and return master items with predictions.

  • Variant/Master: Capture variants with user events and return master items with predictions.

PreviousImporting catalogs via FTPNextCatalog Query

Last updated