Uploading Feeds & Data Files (Catalog, Interests, Content, Users)

Feeding Data into Personyze

UI path: Settings → Customer and session data management → New list (or New container for a session feed), which opens Import Data from a File or Feed.

Almost everything Personyze personalizes on can be fed to it as a data file — a product catalog for recommendations, a content catalog for article recommendations, product interests for cross-sell and affinity targeting, user lists from your CRM, and more. They all travel the same four-step wizard; only the columns differ.

This page covers how to get the file in — the delivery methods, the format rules that trip people up, and the mapping step — using real, field-tested examples.

Download a Template Feed

Start from a ready-made file rather than a blank page. Each template has the correct headers, the right quoting, and a few example rows in the exact format the importer expects — replace the sample rows with your own data and upload. All use placeholder example.com URLs and generic demo products.

The .tsv template downloads as .txt (tabs preserved) — rename to .tsv if your tools expect it, or upload as-is.

Prefer to click through it? Here’s the whole flow — choose a source, format the file, map the columns, import. Detailed reference below.

Upload a feed

1234

Choose how the data arrives

Open Settings → Customer and session data management → New list and pick a source: upload a file (one-off), a URL / RSS / Atom feed or SFTP (kept in sync), or the JSON API (real-time). Same wizard for every feed type — catalog, content, interests, users, transactions.

💡 A file is a snapshot; a URL/SFTP/API feed keeps re-syncing on a schedule.

Next →⛶ Enlarge

Format the file

The importer is comma-delimited. Any cell that itself contains a comma — a list of interests, multiple categories — must be wrapped in double quotes, or it splits into extra columns. Everything else is plain CSV.

💡 The “Detected N columns” count on the next step is your parse check — trust it over how the file looks in Excel.

← BackNext →⛶ Enlarge

Map the columns

Match each detected column to a Personyze field. One key is mandatory — an Internal ID (or SKU / Product Page URL). Map the rest to their fields; add optional Preprocessing or a Mask to clean a value on the way in.

💡 The key must match how your catalog is keyed. “Imports fine but matches nothing” is almost always a key mismatch.

← BackNext →⛶ Enlarge

Review & import

Confirm the mapping and start the import. A file loads once; a URL, SFTP, or API feed keeps syncing from here — re-reading roughly every few minutes so stock, prices, and new records stay current.

← BackDone ✓⛶ Enlarge

✕

Choose how the data arrives

Open Settings → Customer and session data management → New list and pick a source: upload a file (one-off), a URL / RSS / Atom feed or SFTP (kept in sync), or the JSON API (real-time). Same wizard for every feed type — catalog, content, interests, users, transactions.

💡 A file is a snapshot; a URL/SFTP/API feed keeps re-syncing on a schedule.

Next →✕ Close

Format the file

The importer is comma-delimited. Any cell that itself contains a comma — a list of interests, multiple categories — must be wrapped in double quotes, or it splits into extra columns. Everything else is plain CSV.

💡 The “Detected N columns” count on the next step is your parse check — trust it over how the file looks in Excel.

← BackNext →✕ Close

Map the columns

Match each detected column to a Personyze field. One key is mandatory — an Internal ID (or SKU / Product Page URL). Map the rest to their fields; add optional Preprocessing or a Mask to clean a value on the way in.

💡 The key must match how your catalog is keyed. “Imports fine but matches nothing” is almost always a key mismatch.

← BackNext →✕ Close

Review & import

Confirm the mapping and start the import. A file loads once; a URL, SFTP, or API feed keeps syncing from here — re-reading roughly every few minutes so stock, prices, and new records stay current.

← BackDone ✓✕ Close

Four Ways to Deliver a Feed

On step 2 of the wizard you pick how the data reaches Personyze. The choice is really about how often it changes.

• One-off or small → upload a file. Fastest way to load a list once.
• Kept fresh automatically → URL feed. Point Personyze at a live feed URL — a Google Shopping feed, a feed-service export, your platform’s product feed — and it re-reads it on a schedule, so stock, prices, and new products stay current without you re-uploading. This is the usual choice for a product catalog.
• Large & scheduled → SFTP. For big nightly dumps where a public URL isn’t appropriate. SFTP may need to be enabled by your account manager.
• Real-time & you own the backend → API push. POST records as they change.

A live URL, SFTP, or API feed keeps syncing after the first import; a file upload is a point-in-time snapshot you re-upload to refresh.

The Format Rule That Matters Most

Personyze’s file importer is comma-delimited, and that can’t be changed on the upload step. That one fact drives every formatting decision:

• Columns are separated by commas. Not semicolons, not pipes, not tabs (for a genuine tab-separated feed, see the TSV note below).
• If a value inside a cell contains a comma, that cell must be wrapped in double quotes, or the importer splits it into extra columns.

This is standard CSV, but it’s the single most common reason an import misbehaves, so it’s worth stating plainly.

Worked Example: Product Interests

Interests are a list of tags per product — used for cross-sell, affinity segments, and interest-based recommendations. The format that works is two columns, Id and Interest, with the interests comma-separated inside a quoted cell:

Id,Interest
NW-1001,"Sneakers,Footwear,Casual,Running"
NW-1002,"Backpack,Bags,Commuting,Canvas"
NW-1003,"Headphones,Audio,Wireless,Electronics"

Each product’s Interest cell holds a different set of tags. The quotes are what let the interior commas survive. Without them, NW-1001,"Sneakers,Footwear,Casual,Running" becomes five columns instead of two, and the import breaks.
📥 Download the sample interests file — open it in a plain text editor (not a spreadsheet) to see the quoting exactly as the importer needs it.

Separators — What Works and What Doesn’t

TSV note: the wizard accepts .tsv, and a genuine tab-separated feed (like a Google Shopping feed) imports cleanly — tabs are the delimiter, so commas inside descriptions are just text. The comma rule above is about comma-separated files specifically.

The Same Idea for a Category Field

The comma-in-a-quoted-cell pattern isn’t only for interests — any field that holds more than one value works the same way. A category field is the common second case. Two ways to represent it, both valid:

• A hierarchical path in one cell — the Google-feed convention, using > between levels. No commas, so no quoting needed:

  Category
  Footwear > Sneakers
  Electronics > Audio > Headphones

• Multiple categories in one cell — if a product belongs to several, comma-separate them inside quotes, exactly like interests:

  Category
  "Sneakers,Footwear,Running"

The rule is always the same: a comma inside a value means the cell must be quoted. A >-delimited path or a /-delimited one has no commas, so it rides along unquoted.

Carrying Extra Fields in the Same File

You don’t need a separate file per attribute. One row can carry the key plus interests plus category plus anything else you want on the record — brand, availability, a custom tag — and you map each column on step 3:

Id,Interest,Category,Brand,Availability
NW-1001,"Sneakers,Footwear,Casual,Running",Footwear > Sneakers,Acme Footwear,in stock
NW-1003,"Headphones,Audio,Wireless,Electronics",Electronics > Audio > Headphones,Soundry,in stock

Only the quoted Interest cells contain commas, so only they are quoted; the rest ride along as plain columns. Map Id → Internal ID, Interest → Interests, and each remaining column to its Personyze field.

📥 Download the extended sample (Id + Interest + Category + Brand + Availability) alongside the two-column interests sample.

Required Mapping

Every import needs one key column, or Next stays disabled with a red “Missing required mapping”:

• Internal ID — the record’s key (product ID, user ID).
• Product Page URL — the full page URL, as an alternative key.

The key must match what the catalog is already keyed on. If your catalog is keyed on SKU, the file’s Id column must contain that same SKU. An import that completes but “matches no products” is almost always a key mismatch — the IDs loaded fine, they just don’t line up.

Mapping the Columns

On step 3, Personyze shows each detected column and lets you map it to a Personyze field, with optional per-column Preprocessing and Mask.

The column count on this step is your parse check. For the two-column interests file it must read Detected 2 source columns. If it says 6, the quoting was lost in export — fix and re-upload. Judge by what this step reports, not by how the file looks in Excel or Numbers.

For interests: map Id → Internal ID (clears the red error), map Interest → Interests, leave Preprocessing = Pass as is and Mask = Pass everything, then continue to Ready for import.

Building the File (Repeatable Recipe)

If you have a source export with one comma-joined interests column, emit the two-column quoted file with a few lines of Python — csv.writer adds the quotes around any field containing a comma automatically:

import csv
rows = list(csv.DictReader(open('source.csv', encoding='utf-8-sig')))
with open('Id_Interest.csv', 'w', newline='', encoding='utf-8-sig') as f:
    w = csv.writer(f)                 # quotes cells with commas automatically
    w.writerow(['Id', 'Interest'])
    for r in rows:
        ints = ','.join(x.strip() for x in r['Interests'].split(',') if x.strip())
        w.writerow([r['Product ID'], ints])

Product Catalog Feeds

A product catalog is keyed on a product identifier — and you can supply Internal ID, SKU, or both. Only one key is mandatory.

When You Don’t Have a Product ID

If your catalog has no stable ID, Personyze can auto-generate one from a hash of the product-page URL. That’s enough to recognize a product for page views and add-to-cart — the URL is the same each time, so the hash is stable.

Purchase tracking is where a URL hash gets awkward. A thank-you or order-confirmation page usually doesn’t carry the product URLs of what was bought, so there’s nothing to hash. Tracking purchases against hashed IDs is possible but the setup is fiddly. It’s far simpler when you have a real product ID that Personyze can pick up automatically from a page variable — a data-layer value, a tag-manager variable, or a field in the DOM — because the same ID then ties the catalog, the on-site behavior, and the purchase together. If you sell, use a real ID. The URL-hash fallback is for view/click personalization when no ID exists.

The Catalog File

A product catalog uses more columns but the same rules. A typical layout:

Internal ID, SKU, Title, Product Page URL, Main Image URL,
Price, Sale Price, Is in Stock, Rating

Map Internal ID as the key, Main Image URL and Product Page URL so cards render and link, and Price / Sale Price / Is in Stock so widgets can show pricing, discounts, and stock badges. Empty cells are fine — a blank Sale Price just means no discount.
📥 Download the sample product-catalog file — the real column layout used by a live store.
For a live catalog, the practical setup is a URL feed: point Personyze at a feed your platform or a feed service already produces. A standard Google Shopping / Merchant feed (TSV, with id, title, link, price, availability, image_link, product_type, etc.) works directly — Personyze reads those columns and re-polls the URL so stock and prices stay current. If you don’t have a feed yet, tools like Feedoptimise, DataFeedWatch, or your platform’s native export produce one.

The recommendation logic — best sellers, viewed-together, cart-based, interest-based — is set in the action’s algorithm configuration and reads from whatever catalog you feed here. See Setting the Product / Content Feed and Product Recommendation Algorithms.

Images: One Required, More Optional

Each product needs one main image so recommendation cards can render. You can add more image columns beyond that — the extra images feed widgets that rotate or swap the photo on mouse-hover. Map the first to Main Image URL and the rest to the additional image fields.

Carry as Many Custom Fields as You Want

Beyond the standard columns, a feed row can hold any extra data you have — shipping price, quantity-break pricing, per-customer-type prices, tags, brand, color, anything. Three things you can do with a custom field:

• Print it — show it on the recommendation card (a “Free shipping” flag, a member price).
• Filter on it — restrict a recommendation to a brand, color, or category.
• Train the AI on it — give the recommendation model more signal about each product so it ranks better.

Most of the time it’s simple attributes like brand or color; there’s no limit, and unmapped columns are simply ignored.

Buy-Together / Conditional Pricing

You can also carry a per-combination price in the feed — a discounted price that applies when specific products are bought together — so a bundle’s price comes straight from the catalog rather than being calculated. The concept and setup are in Buy-Together Discount for E-commerce Recommendations. (The exact column layout for combination pricing will be added here.)

Content Catalog Feeds

A content catalog (articles, videos, guides) drives content recommendations. The lightest version is just the content URL — Personyze auto-generates an ID and tracks engagement by the URL or URL path, so views and reads attribute correctly without you supplying a key. You can also provide your own Internal ID if you have one.

Everything else works like the product catalog: one main image (more optional for hover widgets), plus any custom columns you want to print, filter, or train on — content type, category, author, publish date, tags.

📥 Download the content-catalog template

User List Feeds (CRM Enrichment for Targeting)

A user list attaches CRM data to your visitors. The minimum is a key plus one attribute:

• Email (or an Internal / CRM ID) as the key, and
• at least one additional column — first name, account type, anything.

You can add as many attribute columns as you like. The important part: whatever you populate here becomes available in targeting, not only inside the action that uses the list. Load a visitor’s first name or account type and you can later build an audience that targets on it — “Account Type is VIP”, “Industry is Retail” — exactly like any other profile field. Deliver it as a file, or keep it in sync via SFTP or a feed URL.

📥 Download the minimal user-list template (Email + First Name)  ·  extended version (with account type, industry).

Cross-Sell & Upsell Feeds (Manual Links)

Cross-sell and upsell recommendations can be driven by an explicit list of which products go with which — the “frequently bought together” or “you might also want” pairings you define yourself. You set these under Manual cross-sell links in the recommendation algorithm; upsell uses the same structure, chosen in the algorithm selection.

The file is simply one link per row: a subject product and a linked product, both by internal ID.

Subject Internal ID,Linked Internal ID
AQB14X,AQB15X
BARR4FJ3,LABAR4114
BGBUFF,BGBUFFA

📥 Download the cross-sell / upsell template

Historical Transaction Feeds

Uploading past purchases lets Personyze train recommendations on real buying behavior and target on purchase history from day one, before it has observed those purchases live. Each row is lean — just enough to say who bought what, when:

• a customer key — email or CRM ID;
• the product ID or SKU that was purchased;
• the transaction time.

No title, quantity, price, or currency is needed — Personyze reads those from the catalog. For the timestamp, use a standard date-time such as 2026-07-21 14:30:00 or a Unix epoch like 1751389200. (Confirm the exact accepted format with your account manager if in doubt.)

📥 Download the transactions template

Content Catalogs and Other Feeds

Beyond the types above, the same wizard loads any tabular data — affinity tables, segment lists, custom attribute sets. Choose the delivery method, get the format right, map a key, map the rest.
A content catalog (articles, videos, guides) works identically — the key columns become the content ID and URL, with title, image, and any attributes you want to recommend or target on. The same holds for cross-sell tables, affinity data, and CRM user lists: choose the delivery method, get the format right, map a key, map the rest.

Finishing the Import

Troubleshooting

Reading a Value Live from the Page Instead

Separate from file import: Personyze can also read a value live from a product page as visitors browse — useful when the data isn’t in a feed. That path uses a CSS selector or JavaScript rather than a file, covered in Grab Data from Your Site. Two field notes worth carrying over:

• Meta tags can’t be clicked with the on-page picker — they live in <head> and aren’t rendered. Type the selector by hand, e.g. meta[property="og:type"].
• On JS-rendered stores (VTEX, React), meta/og tags may be empty at page load and only fill in after hydration, or are served only to search-engine bots via prerender. A selector returning nothing is usually this timing/prerender gap, not a wrong selector. A server-rendered element is more reliable. The GTM dataLayer also carries the reference — but on single-page stores read it carefully, since the dataLayer accumulates across products and an early entry can be the previously-viewed item.

The Short Version

Comma-delimited file; quote any cell containing a comma; map one key column (Internal ID or Product Page URL) that matches how your catalog is keyed; map the rest. Upload a file for a one-off, or point Personyze at a URL / SFTP / API feed to keep it syncing.

Related

• User Profile Data & Bulk Import — the wizard in the context of user/CRM data and keys.
• Grab Data from Your Site — capturing values live from the page instead of a file.
• Setting the Product / Content Feed