Product recommendations

About the tool

A recommendation activity is a saved bundle of catalog + algorithm + rules that the PRZIO SDK can serve when your storefront asks for products.

Product recommendations in PRZIO start with a recommendation activity bound (optionally) to a catalog. You pick one or more recommendation types — behavior signals, AI ranking, or pure rules — and PRZIO returns ordered products that match. Your site renders them with the API response.

Delivery is straightforward: feed your products with feedProduct, optionally track views with trackProductView, then call getRecommendations (or the REST endpoint) wherever you want a carousel — homepage, PDP, cart, post-search, account dashboard, email.

How it works

From a fresh project to a live carousel — at a glance.

1. Create a catalog and feed products. Open Product Recommendation → Catalogs, create a catalog, copy its ID, and call PrzioSDK.feedProduct on each PDP. PRZIO stores categories, tags, brand, price, and any extra keys you send.

   

2. Verify products inside the catalog. Open the catalog row to see every product with image, name, ID, view/purchase counts, categories and tags. Use search and filter to validate your feed before shipping.

   

3. Create an activity and pick algorithms. Switch to the Recommendations tab, create a new activity, set a name, H1 title, max products, and tick one or more recommendation types. Bind the activity to your catalog if you want results scoped to it.

   

4. Add rules and activate. Layer include/exclude rules to filter products further, set status to Activated, and embed via the SDK or REST endpoint.

   

All activities live under your project in PRZIO, alongside personalization, popups, and chatbot. Catalog-scoped data (products, view events) cascades when you delete a catalog.

Catalogs & products

A catalog is a logical bucket for product feeds. You can have many catalogs in one project (e.g. PROD::Products, QA::Products).

What's stored on each product

• productId — your SKU / unique ID.
• environment — defaults to production; you can feed staging products separately.
• thumbnails[] — primary image URLs.
• categoryPaths[] — colon-delimited category trees (e.g. Electronics:Audio:Headphones).
• tags[] — flat tags like sale, bestseller.
• keys{} — every other field you send (title, name, brand, price, slug, …) — used both for display and for rules.

What you see in the catalog

Each product row shows the resolved name (from name, product_name, title, or productId) next to the product ID, plus session views, purchases, cart abandons, categories and tags.

Recommendation types

Pick one or many. When you select multiple, results are merged and capped at your max.

Inclusion / exclusion rules

Layer rules on top of the algorithm to filter the candidate list further. Two lists, each combined with AND or OR.

Operators

Match modes

SDK: feedProduct

Send a product into a catalog from your PDP. Idempotent — calling again updates the same record.

PrzioSDK.feedProduct({
  catalogId: 'YOUR_CATALOG_ID',  // required
  product: {
    id: 'SKU-123',                // required
    thumbnails: ['https://example.com/img.jpg'],
    environment: 'production',    // default
    title: 'Product Title',
    description: 'Product description',
    category: 'Electronics:Phones:Smartphones',
    // OR multiple paths:
    // categories: ['Electronics:Phones:Smartphones', 'Audio:Headphones'],
    tags: ['sale', 'bestseller'],
    price: 99.99,
    brand: 'Acme',
    // any other key — usable in rules and shown on cards
    productPath: '/products/sku-123'
  },
  userIdentifier: 'user-123',     // optional; defaults to przio-uuid cookie
  sessionId: '...'                // optional
});

Special keys

• category / categories[] — colon-delimited paths. Stored on categoryPaths internally.
• tags[] — flat tags.
• thumbnails[] — primary image list. Falls back to image_file, image_url, imageUrl, image on display.
• productPath / url / link — used for the click-through link on rendered cards.

SDK: trackProductView

Record that a visitor viewed a product. Powers mostViewed, recentlyViewed, basedOnRecentlyViewed, and the aiThemeBased seed.

PrzioSDK.trackProductView({
  productId: 'SKU-123',
  catalogId: 'YOUR_CATALOG_ID',   // optional — if you want catalog-scoped views
  environment: 'production',
  userIdentifier: 'user-123'      // optional; defaults to przio-uuid
});

Most teams call this once per PDP load, right after feedProduct. Sessions are de-duplicated, so a visitor who reloads the same product page is counted as a single view per session.

SDK: getRecommendations

Browser-side helper that wraps the REST API and handles cookies / project ID for you.

const { recommendations, fallback, activity } = await PrzioSDK.getRecommendations({
  activityId: 'YOUR_ACTIVITY_ID',
  catalogId: 'YOUR_CATALOG_ID',     // optional override
  productId: 'CURRENT_SKU',         // optional — for similar / wvtw
  userIdentifier: 'user-123',       // optional — for recently viewed / cart / purchase
  excludeProductId: 'CURRENT_SKU',  // optional — drop the current product
  limit: 10,
  environment: 'production',
  recommendationType: 'mostViewed'  // optional override
});

// recommendations = [{ id, thumbnails, categoryPaths, tags, ...keys }]

REST API reference

Same endpoint getRecommendations hits — usable from servers or other clients.

Endpoint

GET https://app.przio.com/api/sdk/recommendations

Query parameters

Example

GET /api/sdk/recommendations
  ?projectId=69f736a98edeecd183a5995c
  &activityId=69f79919546b619b944fb9d0
  &userIdentifier=visitor-uuid-123
  &limit=10

Response shape

A flat list of products with the keys you fed, plus image and category metadata.

{
  "recommendations": [
    {
      "id": "SKU-123",
      "thumbnails": ["https://example.com/sku-123.jpg"],
      "categoryPaths": ["Electronics:Audio:Headphones"],
      "tags": ["sale", "bestseller"],
      "title": "Wireless Headphones",
      "brand": "Acme",
      "price": 99.99,
      "productPath": "/products/sku-123"
    }
  ],
  "fallback": "viewHistory",          // or "random", omitted when none
  "activity": {
    "name": "PROD:: Your Recently Viewed Product",
    "h1Title": "Continue Shopping Your Last Viewed Product",
    "description": "Pick up right where you left off and complete your purchase."
  }
}

• recommendations[] — flat array. Each item has the catalog keys you sent on feedProduct, plus id, thumbnails, categoryPaths, tags.
• fallback — present when the primary algorithm underfilled the carousel. viewHistory = topped up from category similarity, random = activity opted into fallbackToRandom.
• activity — the H1 and description you set on the activity, ready to render above the carousel.

Recipes

Concrete activity setups you can copy.