Catalog Format

Fanplayr natively consumes product data in the format described in this documentation. Providing your catalog in this format is the recommended path and ensures the smoothest integration experience.

If your platform cannot produce this format directly, speak with your account manager about your options. Regardless of how your data is delivered, understanding this structure is valuable — it tells you what Fanplayr knows how to work with, and the more product data you can provide, the better Fanplayr's recommendations and targeting will perform.

TIP

Ready to implement? See the Field Reference for the full technical specification.

Core Concepts

Products and Variants

Fanplayr models products using a PRIMARY / VARIANT relationship, which maps to how most e-commerce stores organise their inventory.

A PRIMARY product is the top-level product as it appears in your catalog — for example, a "Classic Running Shoe". A VARIANT product is a specific variation of that primary product — for example, the same shoe in size 10, colour Blue.

PRIMARY: Classic Running Shoe  // id: "shoe-001"
├── VARIANT: Size 8 / Red      // id: "shoe-001-8-red", primaryProductId: "shoe-001"
├── VARIANT: Size 8 / Blue
├── VARIANT: Size 10 / Red
└── VARIANT: Size 10 / Blue

Variants share most of their attributes with their parent PRIMARY product (such as title, description, and brand) but differ in attributes like size, colour, and price.

Why this matters: Fanplayr's recommendations operate at the PRIMARY product level by default. Providing accurate variant data allows Fanplayr to factor in real-time availability and pricing across all variants when making recommendations.

How this maps to your data

Your store may refer to these as "parent/child products", "configurable/simple products", or simply list each variant as a separate SKU. Any of these can be mapped to the PRIMARY/VARIANT model.

Categories

Fanplayr uses product categories to understand the structure of your catalog and to power category-aware recommendations and targeting.

Categories should represent the full navigational path of a product in your store, using > as a separator:

"Shoes & Accessories > Shoes > Heels"
"Sports & Fitness > Athletic Clothing > Shoes"

A product can belong to multiple categories. The more precise and complete your category paths, the better Fanplayr can target recommendations within specific sections of your store.

Pricing

Fanplayr supports both a current price and an original price (the price before any discount). Providing both allows Fanplayr to:

• Display accurate pricing in recommendation widgets
• Identify and target sale and discounted products
• Report on gross profit when cost data is also provided

Availability

Fanplayr tracks product availability so that out-of-stock products are not recommended to shoppers. The supported availability states are:

Value	Meaning
IN_STOCK	Available to purchase now
OUT_OF_STOCK	Not currently available
PREORDER	Not yet released, but available to pre-order
BACKORDER	Temporarily out of stock, but available to back-order

Images

Product images are displayed directly in recommendation widgets shown to shoppers. Providing high-quality images at 500×500px or larger ensures recommendations are visually appealing and effective.

Audience, Colour, and Other Attributes

Fields like audience (gender, age group), colorInfo, sizes, materials, and patterns help Fanplayr understand the nature of each product in more detail. These attributes improve the relevance of recommendations — for example, ensuring a men's shoe is not recommended on a women's category page.

These fields are optional but valuable, particularly for stores with broad and varied product ranges.

---

Required Fields at a Glance

The following fields are the minimum needed for Fanplayr to effectively index and recommend a product:

Field	Description
id	Unique product identifier — must match the ID tracked in your Fanplayr integration
title	The product name
categories	At least one category path
priceInfo	Current price and currency code
uri	URL of the product page

All other fields are optional, but providing richer data improves recommendation quality.

Catalog file format

The product catalog file format has the following requirements:

• Each catalog item must be contained on a single line.
• The total file size must not exceed 50 MB uncompressed. If your catalog exceeds this, split it and import it in multiple files.
• All items must use the same language and currency. It is not possible to mix languages or currencies within a single catalog, as this would affect AI model training. Manage separate catalogs if your store has multiple views with different languages or currencies.

The following shows a valid catalog file containing two products:

{"id":"SHOE-001","type":"PRIMARY","categories":["Women > Shoes","Sports & Fitness > Athletic Clothing > Shoes"],"title":"Classic Running Shoe","description":"Lightweight everyday running shoe with cushioned sole.","brands":["Stridewell"],"availability":"IN_STOCK","availableQuantity":142,"languageCode":"en","priceInfo":{"price":89.99,"originalPrice":119.99,"currencyCode":"USD"},"uri":"https://www.store.com/shoes/classic-running-shoe","images":[{"uri":"https://www.store.com/images/SHOE-001.jpg","width":500,"height":500}],"colorInfo":{"colorFamilies":["White"],"colors":["Cloud White"]},"sizes":["US:WOMENS:7","US:WOMENS:8","US:WOMENS:9","US:WOMENS:10"],"audience":{"genders":["female"],"ageGroups":["adult"]}}
{"id":"JACK-042","type":"PRIMARY","categories":["Men > Clothing > Jackets","Sale > Men"],"title":"Merino Wool Jacket","description":"Slim-fit merino wool jacket suitable for smart casual occasions.","brands":["Nordvik"],"availability":"IN_STOCK","availableQuantity":37,"languageCode":"en","priceInfo":{"price":149.00,"currencyCode":"USD"},"uri":"https://www.store.com/jackets/merino-wool-jacket","images":[{"uri":"https://www.store.com/images/JACK-042.jpg","width":500,"height":500}],"colorInfo":{"colorFamilies":["Gray"],"colors":["Charcoal"]},"sizes":["US:MENS:S","US:MENS:M","US:MENS:L","US:MENS:XL"],"audience":{"genders":["male"],"ageGroups":["adult"]}}

Next Steps

• Read the Field Reference for the full specification of every supported field, including types, constraints, and examples.
• Speak with your Fanplayr integration team about how your existing product feed maps to this structure.

Legacy Formats

An earlier version of the catalog format is also available for reference. New integrations should use the current format.

View the legacy format reference →