> ## 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.

# Product Import

> Bulk import products from CSV or Excel files.

## Import methods

Alana supports multiple import methods depending on your data source:

| Method                    | How                          | Best for                        |
| ------------------------- | ---------------------------- | ------------------------------- |
| **CSV / Excel**           | File upload                  | Bulk catalog from spreadsheet   |
| **URL scraping**          | Bright Data web scraping     | Scrape product data from a URL  |
| **Shopify / WooCommerce** | Platform connector           | Existing e-commerce store       |
| **MCP inbound**           | AI agent push via MCP API    | Agent-driven catalog population |
| **Dataset import**        | Bright Data dataset delivery | Large-scale data acquisition    |

After any import, the **Bronze stage runs automatically** — products are ingested with an idempotency key to prevent duplicates. Silver normalization and Gold scoring run on demand or via auto-trigger (configurable in [Pipeline Settings](/guides/pipeline-settings)).

## URL import (Bright Data)

Import products by providing a product page URL. Bright Data scrapes the page and extracts structured product data.

```bash theme={null}
curl -X POST "https://app.alana.shopping/api/workspace/{workspaceId}/url-import/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products/my-product",
    "catalogId": "CATALOG_ID"
  }'
```

See the [URL Import guide](/guides/url-import) for details on job management and webhook notifications.

## Supported file formats

The CSV/Excel import endpoint accepts:

* **CSV** (`.csv`) — comma or semicolon separated
* **Excel** (`.xlsx`) — first sheet is used

## Required columns

| Column            | Required | Description                                    |
| ----------------- | :------: | ---------------------------------------------- |
| `title`           |    Yes   | Product name                                   |
| `sku`             |    Yes   | Unique stock-keeping unit                      |
| `price`           |    Yes   | Selling price (numeric)                        |
| `currency`        |    No    | ISO 4217 code (defaults to workspace currency) |
| `description`     |    No    | Product description                            |
| `brand`           |    No    | Brand name (must exist in workspace)           |
| `categoryPath`    |    No    | Category hierarchy separated by `>`            |
| `primaryImageUrl` |    No    | Main product image URL                         |
| `gtin`            |    No    | Global Trade Item Number                       |
| `originalPrice`   |    No    | Original price for discount display            |
| `availability`    |    No    | Stock status (e.g. "in stock", "out of stock") |

Additional columns are stored as flexible `attributes`.

## Import via API

```bash theme={null}
curl -X POST ".../catalog/products/import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@products.csv" \
  -F "catalogId=CATALOG_ID"
```

## Import response

The import returns a summary:

```json theme={null}
{
  "total": 500,
  "created": 487,
  "errors": 13,
  "errorDetails": [
    {"row": 45, "field": "price", "message": "Invalid number format"},
    {"row": 112, "field": "sku", "message": "Duplicate SKU: PROD-112"}
  ]
}
```

## Pipeline auto-processing after import

When products are imported, the Bronze → Silver → Gold pipeline processes them automatically (if configured) or on demand:

1. **Bronze** — raw product stored with idempotency key; duplicate imports are safely skipped
2. **Silver** — fields normalized, duplicates detected, image URLs validated
3. **Gold** — optimization score (0–100) computed across 7 rubric stages; gaps list returned

Trigger Silver and Gold in bulk via [Batch Actions](/guides/batch-actions), or configure auto-trigger in [Pipeline Settings](/guides/pipeline-settings).

## Best practices

<AccordionGroup>
  <Accordion title="Validate before importing">
    Use a small test file (10-20 rows) before importing your full catalog. Check the error details to fix formatting issues.
  </Accordion>

  <Accordion title="Use consistent category paths">
    Follow a consistent hierarchy format: `Level 1 > Level 2 > Level 3`. Inconsistent paths create duplicate categories.
  </Accordion>

  <Accordion title="Include GTINs when possible">
    Products with GTINs score higher on optimization and are required for most shopping feeds (Google, Meta).
  </Accordion>

  <Accordion title="Run Silver + Gold after import">
    After importing, run Batch Silver to normalize fields, then Batch Gold to compute optimization scores. This gives you a quality baseline before publishing. See [Data Enrichment](/guides/data-enrichment).
  </Accordion>
</AccordionGroup>