Product Import

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

URL import (Bright Data)

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

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

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:

{
  "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:

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

Trigger Silver and Gold in bulk via Batch Actions, or configure auto-trigger in Pipeline Settings.

Best practices

Validate before importing

Use a small test file (10-20 rows) before importing your full catalog. Check the error details to fix formatting issues.

Use consistent category paths

Follow a consistent hierarchy format: Level 1 > Level 2 > Level 3. Inconsistent paths create duplicate categories.

Include GTINs when possible

Products with GTINs score higher on optimization and are required for most shopping feeds (Google, Meta).

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.

Getting Started

Core Concepts

Guides

Import methods

URL import (Bright Data)

Supported file formats

Required columns

Import via API

Import response

Pipeline auto-processing after import

Best practices

​Import methods

​URL import (Bright Data)

​Supported file formats

​Required columns

​Import via API

​Import response

​Pipeline auto-processing after import

​Best practices

Import methods

URL import (Bright Data)

Supported file formats

Required columns

Import via API

Import response

Pipeline auto-processing after import

Best practices