Product Data Schema Specifications

Use this specification to format your product information prior to submitting to Listrak. Submitting your data to Listrak in the right format is important for delivering successful campaigns and insights.

Please also use the following schema specifications for other data objects:

Attribute
(Column)
Format
Requirements and Suggestions
ATTRIBUTE (COLUMN)
sku
FORMAT

Attribute Description
The product's unique identifier

Example
9843723-red

Syntax
String
Max. 100 characters

Requirements and Suggestions
  • This attribute is required as a primary key and must be included for every product.
  • If you provide supplemental product data via REST API or data file feed, your SKU must match what is captured by the Listrak JavaScript on your brand's website.
  • When sending updates to a product, ensure your SKU does not change.
  • This attribute's value must match the SKU provided in your Order Items data feed.
  • This attribute is most commonly associated with product variants and is required in all Listrak solution scripts.
ATTRIBUTE (COLUMN)
title
FORMAT

Attribute Description
The product's name

Example
Women's Cabana Top

Syntax
String
Max. 500 characters

Requirements and Suggestions
  • Your product's title must match what is shown on your website and must exclude promotional identifiers and offers such as 20% OFF.
  • For variant products, consider including distinguishing details such as size and color.
  • Ensure your titles are appropriately capitalized. FULL CAPITALIZATION is difficult to read and may be misinterpreted as yelling.
  • Avoid using HTML in your title.
ATTRIBUTE (COLUMN)
price
FORMAT

Attribute Description
The product's price

Example
24.99

Syntax
Decimal

Requirements and Suggestions
  • Ensure your price accurately reflects what is displayed on your website and that the product can be purchased at this price.
  • For products that are on sale, saleprice must be provided.
ATTRIBUTE (COLUMN)
description
FORMAT

Attribute Description
The product's description

Example
By the water or anywhere in the sun, enjoy the outdoors sunburn-free in this comfortable, lightweight cover up.

Syntax
String
Max. 4000 characters

Requirements and Suggestions
  • Your product's description should match what is shown on your product display page and must be free of promotional identifiers and offers like 20% OFF.
  • Ensure your description is appropriately capitalized and punctuated.
  • Avoid using HTML in your description.
  • Products with descriptions exceeding the maximum character limit will not be accepted.
ATTRIBUTE (COLUMN)
imageurl
FORMAT

Attribute Description
The URL of your product’s main image

Example
http://www.example.com/images/abs9843723.jpg

Syntax
String
Max. 500 characters

Requirements and Suggestions
  • Your image URLs must link to the primary image of your product and must be properly encoded to handle special characters and spaces as %20.
  • Each URL must begin with http or https.
  • For consistent rendering, product images should use RGB color space.
  • It is suggested that all images share the same aspect ratio, ideally 1:1 square.
  • Images should be a minimum of 250x250px at a resolution of 72 ppi. Images below this resolution will be accepted but may not render clearly depending on the display size.
ATTRIBUTE (COLUMN)
linkurl
FORMAT

Attribute Description
The URL of your product’s landing page

Example
http://www.example.com/tops/womens-cabana-top.aspx

Syntax
String
Max. 500 characters

Requirements and Suggestions
  • Link URLs must link to your product's display page and must be properly encoded to handle special characters and spaces as %20.
  • Each URL must begin with http or https.
  • Link URLs must link to your brand's domain and should be free of excessive redirects.
ATTRIBUTE (COLUMN)
brand
FORMAT

Attribute Description
The product's brand name

Example
Style Co.

Syntax
String
Max. 50 characters

Requirements and Suggestions
  • If you sell products that you manufacture, you should include your brand's name for those products. This ensures more concise reporting and insights.
  • If you are unable to provide a brand, you should leave this attribute blank. Do not provide values such as N/A or None.
ATTRIBUTE (COLUMN)
category
FORMAT

Attribute Description
The parent category of the product

Example
Swimwear

Syntax
String
Max. 50 characters

Requirements and Suggestions
  • Your category should be the most relevant parent category for each product.
  • Do not include the product's full category tree or path.
  • Consider providing this data from your order management system, merchandising system, or another system of record that contains accurate and complete information.
  • Whenever possible, avoid adding products to a category of Sale. Instead, provide a salestartdate and saleenddate. Or, use onsale to indicate products that are currently on sale.
  • If you are unable to provide a category leave this attribute blank. Do not provide values such as N/A or None.
  • Avoid using HTML in your category.
  • Normalize capitalization across categories, for example, don't supply both Swimwear and SWIMWEAR.
ATTRIBUTE (COLUMN)
subcategory
FORMAT

Attribute Description
The child category of the product

Example
Cover-ups

Syntax
String
Max. 50 characters

Requirements and Suggestions
  • Your subcategory should be the next most relevant child of your category.
  • Do not include the product's full category tree or path.
  • Consider providing this data from your order management system, merchandising system, or another system of record that contains accurate and complete information.
  • If you are unable to provide a subcategory, you should leave this attribute blank. Do not provide values such as N/A or None.
  • Avoid using HTML in your subcategory.
  • Normalize capitalization across subcategories, for example, don't supply both Cover-ups and COVER-UPS.
ATTRIBUTE (COLUMN)
mastersku
FORMAT

Attribute Description
Parent identifier for a group of products available in different versions or variants

Example
9843723

Syntax
String
Max. 100 characters

Requirements and Suggestions
  • Use a unique value or parent SKU for each group of variant product.
  • Use mastersku for a set of products that differ by one or more of these attributes.
  • Include the same attributes for each child product. For example, if a product varies by size and color, submit size and color for every product that share the same value for mastersku
  • Bundled or packaged products should be represented via SKU in their own row.
ATTRIBUTE (COLUMN)
qoh
FORMAT

Attribute Description
The product's quantity on hand

Example
45

Syntax
Integer

Requirements and Suggestions
  • Maintaining a current and accurate measure of QOH ensures that Listrak only recommends available products to shoppers.
  • An accurate QOH is also required by solutions like Back-in-Stock Alerts, Price Drop Alerts, Low Inventory Alerts, and Replenishment which deliver time and inventory sensitive communications.
ATTRIBUTE (COLUMN)
instock
FORMAT

Attribute Description
Explicit indicator of the product's availability

Example
true

Syntax
Boolean

Supported Values
true
false
null

Requirements and Suggestions
  • This status must accurately reflect the product's availability on your website.
  • An accurate in-stock status is also required by solutions like Back in Stock Alerts, Price Drop Alerts, and Low Inventory Alerts.
ATTRIBUTE (COLUMN)
onsale
FORMAT

Attribute Description
Explicit indicator that the product is currently on sale

Example
true

Syntax
Boolean

Supported Values
true
false
null

Requirements and Suggestions
  • Use onsale when salestartdate and saleenddates are not available for the product.
  • Do not supply a value for this attribute and salestartdate and saleenddates.
  • When conflicting values are supplied for all three attributes, Listrak will best determine the product's actual sale state.
ATTRIBUTE (COLUMN)
salestartdate
FORMAT

Attribute Description
The beginning date when the product’s saleprice applies

Example
2018-08-23T17:23:48Z

Syntax
Datetime
ISO 8601

Requirements and Suggestions
  • The salestartdate must be before saleenddate and must be formatted according to ISO 8601 standards.
  • Products that are within the salestartdate and saleenddate window are shown with their saleprice as long as onsale is not also used.
ATTRIBUTE (COLUMN)
saleenddate
FORMAT

Attribute Description
The end date when the product’s saleprice no longer applies

Example
2018-09-23T17:23:48Z

Syntax
Datetime
ISO 8601

Requirements and Suggestions
  • The saleenddate must be after salestartdate and must be formatted according to ISO 8601 standards.
  • Products that are within the salestartdate and saleenddate window are shown with their saleprice as long as onsale is not also used.
ATTRIBUTE (COLUMN)
saleprice
FORMAT

Attribute Description
The product's sale price

Example
21.95

Syntax
Decimal

Requirements and Suggestions
  • Saleprice must match the sale price advertised on your product's landing page.
  • Your product's saleprice must be supplied in addition to its normal price, and must be less than price.
  • Saleprice is shown when a product is within the salestartdate and saleenddate window or when onsale is set to true.
ATTRIBUTE (COLUMN)
discontinued
FORMAT

Attribute Description
Explicit indicator that the product has been permanently discontinued

Example
true

Syntax
Boolean

Supported Values
true
false
null

Requirements and Suggestions
  • Set discontinued to true for products that will no longer be sold. This ensures these products will not be recommended to customers.
  • Leave all product attributes intact when setting discontinued to true. This ensures all future reporting and analytics for discontinued products is still insightful and easily understood.
ATTRIBUTE (COLUMN)
ispurchasable
FORMAT

Attribute Description
Explicit indicator that the product can be recommended to customers

Example
true

Syntax
Boolean

Supported Values
true
false
null

Requirements and Suggestions
  • Products with ispurchasable set to true are eligible to be recommended to customers by Listrak Recommendations.
  • These products are also eligible to be shown by Back-in-Stock Alerts, Price Drop Alerts, Low Inventory Alerts, and Replenishment.
ATTRIBUTE (COLUMN)
isclearance
FORMAT

Attribute Description
Explicit indicator that the product is on clearance

Example
true

Syntax
Boolean

Supported Values
true
false
null

Requirements and Suggestions
  • For enhanced Listrak CRM reporting and analytics, set isclearance to true for products that are currently being sold on clearance.
  • isclearance can also also be used to inform Listrak Recommendations and Abandonment campaigns.
ATTRIBUTE (COLUMN)
isoutlet
FORMAT

Attribute Description
Explicit indicator that the product is sold at outlet

Example
true

Syntax
Boolean

Supported Values
true
false
null

Requirements and Suggestions
  • For enhanced Listrak CRM reporting and analytics, set isoutlet to true for products that are currently being sold at outlet.
  • isoutlet is also be used to inform Listrak Recommendations and Abandonment campaigns.
ATTRIBUTE (COLUMN)
color
FORMAT

Attribute Description
The product's color

Example
Blue

Syntax
String
Max. 100 characters

Requirements and Suggestions
  • When supplying your product's color, include the full color and do not abbreviate using single letters or numbers.
  • Do not include hex values.
  • For multi-color products, separate colors using a /. For example, Blue/Green/Red.
  • Do not separate colors using commas or semicolons.
  • Ensure your colors are appropriately capitalized.
ATTRIBUTE (COLUMN)
style
FORMAT

Attribute Description
The product's style

Example
Lightweight

Syntax
String
Max. 100 characters

Requirements and Suggestions
  • Maintaining accurate and consistent conventions in the style attribute will result in more accurate Listrak Recommendations and Listrak CRM reporting.
  • Ensure your styles are appropriately capitalized.
ATTRIBUTE (COLUMN)
size
FORMAT

Attribute Description
The product's size

Example
Small

Syntax
String
Max. 50 characters

Requirements and Suggestions
  • When supplying your product's size, include the full size and do not abbreviate whenever possible. For example, provide Large instead of L.
  • Ensure your styles are appropriately capitalized.
ATTRIBUTE (COLUMN)
gender
FORMAT

Attribute Description
The product's target gender

Example
F

Syntax
Single character

Supported Value
M (Male)
F (Female)
N (Neither/Not Applicable)

Requirements and Suggestions
  • Unisex products should be supplied with a gender of N (Neither/Not Applicable).
ATTRIBUTE (COLUMN)
msrp
FORMAT

Attribute Description
The product's suggested retail price

Example
31.99

Syntax
Decimal

Requirements and Suggestions
  • Manufacturer's suggested retail price (MSRP) can be supplied for enhanced Listrak CRM reporting.
ATTRIBUTE (COLUMN)
unitcost
FORMAT

Attribute Description
The product's per unit cost

Example
6.89

Syntax
Decimal

Requirements and Suggestions
  • Unitcost and price are used to determine each product's profit margin. This value is used from enhanced Listrak CRM reporting.
ATTRIBUTE (COLUMN)
reviewproductid
FORMAT

Attribute Description
The product's identifier used by third-party reviews provider

Example
40245

Syntax
String
Max. 100 characters

Requirements and Suggestions
  • This attribute is used for Ratings and Reviews and should be supplied to you by your third-party product reviews provider.
ATTRIBUTE (COLUMN)
reviewurl
FORMAT

Attribute Description
The URL of the product’s review landing page

Example
http://www.example-reviews.com/?reviewproductid=40245.aspx

Syntax
String
Max. 500 characters

Requirements and Suggestions
  • This attribute is used for Ratings and Reviews.
  • reviewurl may lead to your product's review landing page on your own domain or a landing page supplied by your third-party reviews provider.
ATTRIBUTE (COLUMN)
meta1
FORMAT

Attribute Description
Supplemental product information

Syntax
String
Max. 500 characters

Requirements and Suggestions
  • Supply a custom value describing your product that can be used for enhanced Listrak CRM reporting or solution functionality.
  • This field can also be a comma delimited list and has operations such as equals, contains, is not blank, etc. associated to it for additional operational level performance in Listrak and Listrak CRM.
  • Though you may add boolean values to this field, it is of string type and will not convert to provide operations such as is true or is false.
ATTRIBUTE (COLUMN)
meta2
FORMAT

Attribute Description
Supplemental product information

Syntax
String
Max. 500 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
meta3
FORMAT

Attribute Description
Supplemental product information

Syntax
String
Max. 500 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
meta4
FORMAT

Attribute Description
Supplemental product information

Syntax
String
Max. 500 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
meta5
FORMAT

Attribute Description
Supplemental product information

Syntax
String
Max. 500 characters

Requirements and Suggestions
ATTRIBUTE (COLUMN)
related_sku1 related_sku2 _______________ related_sku25
FORMAT

Attribute Description
SKU of product related to the SKU of this row

Example
9843723-green

Syntax
String
Max. 100 characters

Requirements and Suggestions
  • This field is required if you are supplying a related product feed.
  • If a Related Product Recipe is utilized in Product Recommendations, this SKU will be returned if the product SKU is being referenced
ATTRIBUTE (COLUMN)
related_type1 related_type2 _______________ related_type25
FORMAT

Attribute Description
Describes the relation to the SKU of this row

Example
Cross-sell
Similar
Accessory

Syntax
String
Max. 100 characters

Requirements and Suggestions
  • If a Related Product Recipe is utilized in Product Recommendations, a drop down list of all related types will be available.
ATTRIBUTE (COLUMN)
related_rank1 related_rank2 _______________ related_rank25
FORMAT

Attribute Description
Rank of importance will determine the order in which product recommendations are shown

Syntax
Integer
1-25

Requirements and Suggestions