Catalogs

Introduction

Catalogs store any items without direct relationship to the customer. Catalog is a lookup table with one primary key (item_id). It can store any table with fixed columns, for example the list of your products, prices, URL to images and stock availability.

You can search in a catalog by key. Catalogs can be updated on the fly and reflect the current state of stock or online articles. Lookup results are cached, so it can take few seconds for update to show up in new query results.

The most common use cases for catalogs are:

  • In e-commerce - storing a list of products and product categories
  • In publishing - storing article and section details

Two types of catalog

  • general catalog (without special predefined IDs, only item_id as primary key is required)
  • product catalog (with special predefined product related IDs listed below)

Product catalog

Unlike general catalog, product catalogs are handled in different way. Exponea gives you opportunity to mark catalog columns with special predefined IDs listed below. This can significantly improve your Recommendations experience and some of product catalogs are prerequisite for Exponea Inventory Management feature. Exponea is making daily snapshots of product catalogs as well so we are able to calculate product stock level in time.

Full list of recommended product catalog columns

Column
Type
Description

item_id

string

Unique identifier of your product variants (sku, ean - considering sizes, colors and so...)

product_id

string

Product identifier (not considering sizes, colors…), more products of same type has same product id.

title

string

Name of product. E.g.: Black fitted crew neck t shirt

description

string

Description of product.

active

boolean

Information about product availability. Options: true/false; 0/1

brand

string

Brand of product. E.g.: Nike, Adidas...

category_ids

list

Internal id of category from your e-commerce tool. E.g.: 12345

category_level_1

string

Name of first level category, where product belongs. E.g.: Shoes

category_level_2

string

category_level_3

string

category_path

string

Full path of category tree, where product belongs delimited by pipe “|". E.g.: Tops | T-shirts | V-neck t-shirts

color

string

Main color of product. E.g.: red

gender

string

Gender for which is product designed. Options: Male / Female / Unisex

image

string

Url to main product img (not thumbnail). E.g.: http://…

lead_time

string

Time which is need for re-stocking of product from you supplier. E.g.: 7

supplier

string

Identification of supplier for this product (name / id).

size

string

Size of product for current EAN / SKU. E.g.: XL / 12 / ...

url

string

Direct url to product on your site. E.g.: http;//

stock_level

integer

Number of product of given ean in stock.

cost_per_unit

float

Price of product without your margin (cost of product).

discount_percentage

float

Percentual discount. E.g.: 50

price

float

Final price displayed to your customer (already discounted by “discount” field)

returned_products

string

Number of returned products of this type (per ean / sku).

date_added

timestamp

Time of first occurrence on your stock.

Importing

(full catalog Import documentation here)
Catalog data can come from:

  • Copy & paste
  • CSV file (one time upload or from a public URL)
  • external database (available integrations are MySQL, PostgreSQL, BigQuery, MSSQL)

You can run a one time import or schedule repeated catalog updates from external sources. Catalog items are not removed, but updated.

Is product catalog?

You can mark catalog as product catalog or leave as general catalog. When catalog is marked as product you have predefined IDs available (gender, size, brand...) to assign to you columns. It is strongly recommended to assign as many IDs as it is possible so you will have better Exponea experience in features like Recommendations or Inventory Management

Assigning IDs

Common use cases

Catalogs are useful when you only have 'item_id' available in the context, for example from event (aggregate) or from recommendation.

Personalization

Example - showing a Web Layer with the last visited product on the homepage

Requirements

  • catalog with required columns (item_id, picture_url, link_url, price, available).
  • event tracking (Track event view_item on every page visit of a product page. Track with property item_id that matches the item_id in the product catalog)

Design a new Web Layer where you can show an item based on the last viewed item. Create an aggregate to get last(view_item) 'item_id'. In personalization, find your aggregate and use it in catalog lookup personalization.

Usage of catalog:

{% set item = catalogs.products.item_by_id(aggregates['586e0b8d830434e7cc369263']) %}

To check if item is available and print values from catalog:

{% if item and item.available == "true" %}
    {{ item.picture_url }}
    {{ item.link_url }}
    {{ item.price }}
{% endif %}

Recommendations (BETA)
Catalog is required when using recommendation engine to recommend items. Recommendation result is a list of item_ids. To print recommendation results in email or Web Layer you can use catalog lookup as in the example below.

<ul id="recommendations">
  {% for item in recommendations['58aee25afb6009bfe0852332'][:8] %}
  <li> <a href="{{ item.link_url }}">{{ item.title }}</a> </li>
  {% endfor %}
</ul>