AutoProductCatalog

Build a CleverTap product catalog from event data you already send to CleverTap — no separate product feed required.

Use the result with Recommendations.

Disclaimer

Use this tool at your own risk. It is provided as-is, without warranty of any kind. You are responsible for how you run it, what data you process, and any catalogs or files it creates in your CleverTap account.

• Catalogs 2.0 required — This only works with Catalogs 2.0. If you do not have access to it, reach out to Sales to have it enabled for your account.
• Product events only — Use an event that describes products, not users. Event properties should contain product fields (SKU, name, image URL, price, category, etc.). Do not use events that include personally identifiable information (PII) or other sensitive data, such as email addresses, phone numbers, names, physical addresses, payment details, government IDs, or free-text fields that may contain user content.
• Review before upload — Inspect the generated CSV and field mapping before uploading. Confirm that only intended product attributes are included and that no sensitive properties were mapped by mistake.
• Credentials stay on your machine — CleverTap and OpenAI credentials are read from your local .env file. Do not commit .env, API keys, or generated output files (for example catalog.csv) to version control or share them publicly.
• AI mapping sends samples to OpenAI — In the default --mode llm, up to 20 sample events are sent to OpenAI to suggest field mappings. If your events might contain PII or other sensitive data, use --mode manual instead, or do not use this tool until your event schema is product-only.
• No CleverTap support obligation — This is a community utility, not an officially supported CleverTap product. CleverTap is not responsible for data loss, incorrect catalogs, API usage, or compliance issues arising from your use of this tool.

Requirements

• Python 3.11+
• uv (recommended) or pip
• CleverTap Account ID and Passcode (Settings → Project)
• Email address (CLEVERTAP_CREATED_BY, required for catalog upload)
• Optional: OpenAI API key for AI-assisted field mapping

Setup

git clone https://github.com/SidJain1412/AutoProductCatalog
cd AutoProductCatalog
uv sync
cp .env.example .env

Edit .env:

CLEVERTAP_ACCOUNT_ID=YOUR_ACCOUNT_ID
CLEVERTAP_PASSCODE=YOUR_PASSCODE
CLEVERTAP_REGION=eu1
CLEVERTAP_CREATED_BY=you@example.com
OPENAI_API_KEY=sk-...                 # optional

Set CLEVERTAP_REGION to match your dashboard URL:

Region	Value	Dashboard
Europe (default)	eu1	eu1.dashboard.clevertap.com
India	in1	in1.dashboard.clevertap.com
Singapore	sg1	sg1.dashboard.clevertap.com
United States	us1	us1.dashboard.clevertap.com
Indonesia	aps3	aps3.dashboard.clevertap.com
Middle East (UAE)	mec1	mec1.dashboard.clevertap.com
South Korea	sk1	sk1.dashboard.clevertap.com

Usage

uv run main.py

The wizard will ask for:

• Event name (e.g. Product Viewed)
• Field mapping (AI-suggested or manual)
• Catalog name

Options

uv run main.py [OPTIONS]

  --mode {llm,manual}          Mapping mode (default: llm; falls back to manual without OPENAI_API_KEY)
  --days DAYS                    Days of event history to fetch (default: 60)
  --max-events N                 Maximum events to fetch (default: 10,000)
  --output PATH                  CSV output path (default: catalog.csv)
  --catalog-name NAME            Catalog name (prompted if omitted)
  --skip-upload                  Only generate CSV; do not upload to CleverTap
  --min-property-presence PCT    Min % of sample events a property must appear in (default: 60)

Examples

# Full run: map fields, generate CSV, upload catalog
uv run main.py

# CSV only
uv run main.py --skip-upload

# Manual mapping, last 30 days
uv run main.py --mode manual --days 30

# Stricter property filter
uv run main.py --min-property-presence 80

Event requirements

Choose an event that represents product interactions (for example Product Viewed, Added to Cart, or Charged with per-item product fields). The event must not contain user-level or sensitive data — only product attributes you are comfortable exporting into a catalog.

Your event should include properties that can map to:

Catalog field	Required	Description
identity	Yes	Unique product ID (SKU, product ID, etc.)
name	Yes	Product display name
image_url	Yes	Public image URL

You can also map extra properties (price, category, brand, etc.) as custom catalog attributes.

Output

• CSV — catalog.csv by default (or --output path), one row per unique product
• Catalog URL — printed after upload, e.g.
  https://eu1.dashboard.clevertap.com/<account_id>/catalogs/<catalog_id>/product

License

Apache License 2.0 — see LICENSE.