> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Products

> Product data model, optimization scores, and feed readiness.

## Overview

**Products** are the core data unit in Alana Shopping. Each product lives inside a catalog and contains the content, pricing, and metadata needed for e-commerce feeds.

## Product properties

| Field             | Type   | Description                                                 |
| ----------------- | ------ | ----------------------------------------------------------- |
| `title`           | string | Product display name                                        |
| `description`     | string | Full product description                                    |
| `brand`           | string | Brand name                                                  |
| `categoryPath`    | string | Category hierarchy (e.g. "Apparel > T-Shirts > Men's")      |
| `price`           | number | Current selling price                                       |
| `originalPrice`   | number | Original price (for showing discounts)                      |
| `currency`        | string | ISO 4217 currency code                                      |
| `primaryImageUrl` | string | Main product image URL                                      |
| `sku`             | string | Stock-keeping unit                                          |
| `gtin`            | string | Global Trade Item Number (EAN/UPC)                          |
| `availability`    | string | Stock status                                                |
| `attributes`      | object | Flexible key-value attributes (color, size, material, etc.) |

## Optimization score

Every product receives an **optimization score** from 0 to 100, calculated by the score engine. The score considers:

* Title quality (length, keyword density, readability)
* Description completeness and richness
* Image availability and resolution
* Required field population (SKU, GTIN, price)
* Category path depth
* Attribute completeness

### Score ranges

| Range  | Rating     | Color    |
| ------ | ---------- | -------- |
| 90–100 | Excellent  | Green    |
| 70–89  | Good       | Sky blue |
| 50–69  | Needs work | Amber    |
| 0–49   | Poor       | Red      |

## Feed readiness

A product is **feed-ready** when all required fields for its target feed format are populated. The `feedReady` boolean flag is automatically computed and indicates whether the product can be exported to Google Shopping, Meta Commerce, or other channels.

## Pipeline stage fields

Every product moves through the Bronze → Silver → Gold processing pipeline. The following fields track pipeline progress:

| Field                | Type   | Description                                                                       |
| -------------------- | ------ | --------------------------------------------------------------------------------- |
| `source_type`        | string | Import source: `manual`, `csv`, `url_scrape`, `shopify`, `dataset`, `mcp_inbound` |
| `source_identifier`  | string | Idempotency key — prevents duplicate Bronze ingest from the same source record    |
| `pipeline_stage`     | string | Current stage: `bronze`, `silver`, `gold`                                         |
| `silver_result`      | object | Normalization result: fields mapped, duplicates detected, URLs validated          |
| `gold_result`        | object | Scoring result: score (0–100), gaps list, missing fields                          |
| `score_history`      | array  | Historical optimization scores with timestamps                                    |
| `optimization_score` | number | Current score (0–100) computed by the unified Gold score function                 |

See [Data Pipeline](/concepts/data-pipeline) for the full pipeline architecture.

## Bulk import

Products can be imported in bulk from multiple sources:

* **CSV / Excel** — column-mapped spreadsheet upload
* **URL scraping** — Bright Data web scraping from a product URL
* **Shopify / WooCommerce connector** — direct platform sync
* **MCP inbound** — AI agents pushing products via the MCP Tools API
* **Dataset import** — bulk dataset delivery from Bright Data

After import, Bronze stage is automatic. Silver normalization and Gold scoring can be triggered manually or configured to auto-run via [Pipeline Settings](/guides/pipeline-settings).

See the [Product Import guide](/guides/product-import) for detailed instructions.