Field Reference

This page documents every field supported in the Fanplayr Product Catalog. Use it to understand what product data Fanplayr can work with, and how each field should be structured.

Not sure where to start?

If you're new to the catalog format, read the Overview first. It explains key concepts like the PRIMARY/VARIANT product model and which fields matter most.

Product

The Product object is the top-level structure for each item in the catalog. The TypeScript interface below gives developers a quick overview of the full shape — hover over any type to explore it. Non-technical readers can skip straight to the field descriptions below.

interface Product {
  id: string; // required
  type?: Type;
  primaryProductId?: string;
  categories: string[]; // required
  title: string; // required
  brands?: string[];
  description?: string;
  languageCode?: string;
  priceInfo: PriceInfo; // required
  availability?: Availability;
  availableQuantity?: number;
  uri: string; // required
  images?: Image[];
  audience?: Audience;
  colorInfo?: ColorInfo;
  sizes?: string[];
  materials?: string[];
  patterns?: string[];
  conditions?: string[];
}

Example

A complete example of a valid Product object:

{
  "id": "805371A",
  "type": "PRIMARY",
  "categories": ["Women > Shoes", "Sports & Fitness > Shoes"],
  "title": "Red Shoes",
  "description": "Fancy red shoes",
  "brands": ["Designer Brand"],
  "availability": "IN_STOCK",
  "availableQuantity": 30,
  "languageCode": "en",
  "priceInfo": {
    "price": 89.99,
    "originalPrice": 119.99,
    "currencyCode": "USD"
  },
  "uri": "https://www.store.com/shoes/red-shoes",
  "images": [
    {
      "uri": "https://www.store.com/images/805371.jpg",
      "width": 500,
      "height": 500
    }
  ]
}

INFO

The above example includes line-breaks for readability. In a catalog file, each product must be a single JSON-encoded line. The file must be encoded in UTF-8.

Fields

id

• Type: string
• Required
• Maximum size: 128 bytes

A unique identifier for this product within the catalog. No two products in the same catalog may share the same id.

This value must match the product ID tracked in your Fanplayr integration — it is used to correlate catalog data with shopper behaviour such as product page views and purchases.

type

• Type: enum Type
• Default: inferred from primaryProductId

Indicates whether this product is a top-level product (PRIMARY) or a variation of one (VARIANT). See Type for the full list of values.

In most cases this field can be omitted — Fanplayr will infer the correct value based on primaryProductId:

• Defaults to 'PRIMARY' when primaryProductId is absent or equal to id.
• Defaults to 'VARIANT' when primaryProductId differs from id.

primaryProductId

• Type: string

The id of the PRIMARY product this variant belongs to. Used to group variants under their parent product.

• For PRIMARY products: leave empty, or set to the same value as id.
• For VARIANT products: must be set to the id of the parent PRIMARY product.

categories

• Type: string[]
• Required (at least one entry)
• Maximum size: 1,000 bytes (encoded as JSON)

The categories this product belongs to. A product may belong to multiple categories. Providing the full category path — rather than just the leaf category — significantly improves recommendation and search quality.

Use > to separate hierarchy levels. If > appears in a category name, replace it with another character such as "|".

"categories": [
  "Shoes & Accessories > Shoes",
  "Sports & Fitness > Athletic Clothing > Shoes"
]

title

• Type: string
• Required
• Maximum size: 500 bytes

The product name as it appears on your storefront. This value is displayed in recommendation widgets shown to shoppers, so it should match your storefront exactly.

brands

• Type: string[]
• Maximum size: 1,000 bytes (encoded as JSON)

The brand associated with this product. Used to power brand-aware filtering and recommendations. Multiple brands are supported if needed.

description

• Type: string
• Maximum size: 500 bytes

A plain-text description of the product. Used to improve recommendation relevance. Providing a good description helps Fanplayr better understand what the product is.

languageCode

• Type: string

The language used in text fields such as title and description. Must be a valid BCP 47 language tag (e.g. "en", "fr", "de").

priceInfo

• Type: object PriceInfo
• Required

Pricing information for this product, including current price, original price, and currency. See PriceInfo for full details.

availability

• Type: enum Availability
• Default: 'IN_STOCK'

The current availability of the product. Fanplayr uses this field to avoid recommending products that shoppers cannot purchase. See Availability for the full list of values.

availableQuantity

• Type: number

The number of units currently in stock.

uri

• Type: string
• Required

The canonical URL of the product detail page. Used as the link destination when a product is shown in a recommendation widget.

images

• Type: object[] Image

A list of images for this product. Product images are displayed directly in recommendation widgets — providing accurate, high-quality images is strongly recommended. Images should be at least 500×500px. See Image for full details.

audience

• Type: object Audience

The intended audience for this product. Providing audience data helps Fanplayr serve more relevant recommendations — for example, avoiding recommending men's products on a women's category page. See Audience for full details.

colorInfo

• Type: object ColorInfo

Colour information for the product. Particularly valuable for fashion and apparel stores. Providing this field enables colour-based filtering, improves recommendations, and allows colour chips to be shown in product recommendation widgets. See ColorInfo for full details.

sizes

• Type: string[]
• Maximum: 20 values

The available sizes for this product. To represent different size systems or size types, use the format [[size_system:]size_type:]size_value]:

• "US:MENS:M" — size system US, size type MENS, size value M
• "GIRLS:27" — no size system, size type GIRLS, size value 27
• "32 inches" — no size system or type, size value 32 inches

materials

• Type: string[]
• Maximum: 20 values

The material or materials this product is made from (e.g. "leather", "cotton", "wood").

patterns

• Type: string[]
• Maximum: 20 values

The pattern or graphic print of the product (e.g. "striped", "polka dot", "paisley").

conditions

• Type: string[]
• Maximum: 1 value

The condition of the product. Although defined as an array for consistency with other fields, only one value is supported. Use the standard values where possible:

• "new"
• "refurbished"
• "used"

---

Types

The following types are referenced by fields in the Product object.

Type

The type of a product. Determines whether this product is a top-level item or a variation of another.

Value	Description
"PRIMARY"	A top-level product. PRIMARY products may have multiple VARIANT products grouped beneath them.
"VARIANT"	A variation of a PRIMARY product. Variants typically share attributes like title and brand with their parent, but differ in properties like size, colour, or price.

PriceInfo

Pricing information for a product.

interface PriceInfo {
  currencyCode: string; // required
  price: number; // required
  originalPrice?: number;
  cost?: number;
}

currencyCode

• Type: string
• Required

The ISO 4217 3-letter currency code for all prices in this object (e.g. "USD", "AUD", "GBP").

price

• Type: number
• Required

The current selling price of the product. This is the price shown to shoppers and used in recommendation widgets.

originalPrice

• Type: number

The price of the product before any discount. If omitted or zero, defaults to the value of price. When provided, originalPrice must be greater than or equal to price. Providing this field enables Fanplayr to identify and target sale and discounted products.

cost

• Type: number

The cost of goods for this product. Used internally for gross profit reporting. This value is never shown to shoppers.

Availability

The availability state of a product. Fanplayr uses this to avoid recommending products that shoppers cannot purchase.

• Default: "IN_STOCK"

Value	Description
"IN_STOCK"	The product is available to purchase now.
"OUT_OF_STOCK"	The product is not currently available.
"PREORDER"	The product has not yet been released but is available to pre-order.
"BACKORDER"	The product is temporarily out of stock but available to back-order.

Image

An image associated with a product. Images are displayed directly in recommendation widgets. Images should be at least 500×500px.

interface Image {
  uri: string; // required
  width?: number;
  height?: number;
}

uri

• Type: string
• Required

The URL of the image. Must be a valid UTF-8 encoded URI with a maximum length of 5,000 characters.

width

• Type: number

The width of the image in pixels.

height

• Type: number

The height of the image in pixels.

Audience

The intended audience for a product, used to improve recommendation relevance.

interface Audience {
  genders?: Gender[];
  ageGroups?: AgeGroup[];
}

genders

• Type: ('male' | 'female' | 'unisex')[]
• Maximum: 5 values

The genders this product is intended for. Use the standard values where possible:

• "male"
• "female"
• "unisex"

ageGroups

• Type: ('newborn' | 'infant' | 'toddler' | 'kids' | 'adult')[]
• Maximum: 5 values

The age groups this product is intended for. Use the standard values where possible:

• "newborn" — up to 3 months old
• "infant" — 3–12 months old
• "toddler" — 1–5 years old
• "kids" — 5–13 years old
• "adult" — typically teens or older

ColorInfo

Colour information for a product. Particularly valuable for fashion and apparel stores. Providing this field enables colour-based filtering, improves recommendations, and allows colour chips to be shown in product recommendation widgets.

interface ColorInfo {
  colorFamilies?: string[];
  colors?: string[];
}

colorFamilies

• Type: string[]
• Maximum: 5 values

The broad colour family or families this product belongs to. Normally a product has only one colour family — use "Mixed" rather than multiple values where appropriate.

Use the standard values where possible:

"Red" "Pink" "Orange" "Yellow" "Purple" "Green" "Cyan" "Blue" "Brown" "White" "Gray" "Black" "Mixed"

colors

• Type: string[]
• Maximum: 75 values

The specific colour name or names for this product, as they appear on your storefront (e.g. "Midnight Navy", "Rose Gold"). These may differ from the standard colorFamilies values. Normally a product has only one colour — use "Mixed" rather than multiple values where appropriate.