# Product Catalog Ingestion via API

# Product Catalog Ingestion

Intempt supports two ways of ingesting product data into the Recommendations engine:

1. **Catalog Source Integration** — recommended for large or feed-based catalogs
2. **Direct API-Based Product Ingestion** — recommended for programmatic sync jobs (e.g. WooCommerce / Shopify)

Both approaches ensure your product information remains accurate, up to date, and usable for recommendations and personalization.

This document explains **both methods** and highlights important rules to avoid common ingestion issues—such as accidentally creating anonymous users.

---

## 1. Catalog Source Integration (JSON or XML)

Use this approach when your product catalog is available as a **publicly hosted JSON or XML feed**.

This is the recommended method for:

* Shopify stores
* WooCommerce stores
* Large catalogs (more than 1,000 products)
* Nightly or scheduled cron-based sync jobs

---

### Supported File Types

Catalog feeds can be provided as:

* **JSON**
* **XML**

Your feed must contain a **products array**.

---

### JSON Example

```json
{
  "products": [
    {
      "product": {
        "id": "123",
        "title": "Product Name",
        "description": "Details...",
        "url": "https://example.com/product",
        "image_link": "https://example.com/image.jpg"
      }
    }
  ]
}
```

---

### Minimum Required Product Fields

Each product must include the following fields:

| Field         | Description               |
| ------------- | ------------------------- |
| `id`          | Unique product identifier |
| `title`       | Product name              |
| `description` | Textual description       |
| `url`         | Product page URL          |
| `image_link`  | Image URL                 |

These fields ensure every product is visible, linkable, and usable within Intempt’s Recommendations engine.

---

### Creating a Catalog Source

#### Step 1 — Initiate

1. Go to **Recommendations**
2. Click **Manage Catalog Sources**
3. Click **Create Catalog Source**
4. Enter a name for your catalog

---

#### Step 2 — Configure Source URL

1. Enter the feed URL (JSON or XML)
2. Enable authentication only if required
3. Click **Next**

---

#### Step 3 — Map Fields

Map your feed fields to Intempt’s required catalog fields:

| Source Field  | Intempt Field |
| ------------- | ------------- |
| `id`          | `id`          |
| `title`       | `title`       |
| `link`        | `url`         |
| `description` | `description` |
| `image_link`  | `image_link`  |
| `price`       | `price`       |

Optional fields you may map include:

* `categories`
* `tags`
* `brand`
* `variants`
* custom fields

Enable **Sync Field** for any field you want Intempt to ingest.

Click **Create Catalog Source** to complete the setup.

---

### Managing Catalog Sources

Once created, Intempt automatically:

* fetches updates from the feed
* updates existing product records
* keeps the catalog synchronized

You can edit a catalog source at any time to:

* change the feed URL
* update authentication credentials
* modify field mappings

---

### Deleting a Catalog Source

1. Go to **Manage Custom Catalog Sources**
2. Open the dropdown next to the source
3. Click **Delete**

This is useful for removing test catalogs or deprecated sources.

---

## 2. Direct API-Based Product Ingestion

> **Important:** Prevents accidental anonymous user creation

You can also ingest products directly using the **Track API**, provided the payload is structured correctly.

This method is commonly used for:

* WooCommerce sync jobs
* Shopify webhooks
* Custom backend or ERP integrations

---

### Rule (Very Important)

If `productId` is provided:

* You **do not** need to send `userId` or `profileId`

This prevents Intempt from creating anonymous users during bulk product ingestion.

---

### API Payload Format (Correct)

Use the following structure when sending product data directly to Intempt:

```json
{
  "productId": "123",
  "data": {
    "title": "Wine Bottle",
    "amount": 150,
    "quantity": 4,
    "categories": [
      { "id": 2300, "name": "Closed Reflex", "slug": "closed-reflex" },
      { "id": 2151, "name": "Optics", "slug": "optics" }
    ],
    "images": [
      {
        "id": 11689,
        "src": "https://example.com/image1.jpg",
        "name": "image1.jpg"
      },
      {
        "id": 11690,
        "src": "https://example.com/image2.jpg",
        "name": "image2.jpg"
      }
    ],
    "tags": [
      { "id": 10, "name": "Featured" },
      { "id": 14, "name": "Best Seller" }
    ]
  }
}
```

---

### Supported Nested Data

You may include any nested product data inside the `data` object, including:

* categories (any depth)
* tags
* images
* metadata
* product attributes
* custom WooCommerce / Shopify fields
* variant data

---

### Wrong Payload (Causes Anonymous Users)

Do **not** send product arrays as part of an event:

```json
{
  "eventTitle": "Products",
  "data": {
    "products": [ ... ]
  }
}
```

This causes Intempt to create a user profile per event, resulting in hundreds of anonymous users.

---

### Correct: Treat Product Sync as Product Records

Use:

```json
{
  "productId": "...",
  "data": { ... }
}
```

Not:

```json
{
  "eventTitle": "...",
  "userId": "...",
  "data": {
    "products": [ ... ]
  }
}
```

---

### Why `productId` Removes the Need for `userId` / `profileId`

When `productId` is included:

* Intempt switches into catalog ingestion mode
* no new user profile is created
* no profile merging logic is triggered
* the product is stored directly in the catalog

This is the correct and intended approach for WooCommerce, Shopify, and custom backend product syncs.

---

## Summary

Product catalog ingestion in Intempt supports:

* **Catalog Source Integration**
  For JSON or XML feeds managed through the UI

* **Direct API-Based Product Ingestion**
  For programmatic product syncs

* **No `userId` / `profileId` required when using `productId`**
  Prevents anonymous users and ensures clean ingestion

* **Rich nested product structures**
  Including categories, tags, images, metadata, and variations

Using the appropriate ingestion method ensures your product catalog is imported cleanly and remains fully compatible with Intempt’s Recommendations engine.