Imports

Imports let you bring first-party catalog data into Extralt without crawling your own storefront first.

A run crawls ecommerce pages. An import uploads catalog data you already have. Both produce Captures, and Captures move through the same Enrich and Explore pipeline.

When to use imports

Use imports when you want your own product catalog inside Extralt:

• Seed Extralt with your current product data
• Compare your catalog against open-web competitor observations
• Enrich your own products with the same taxonomy, attributes, and signals as extracted products
• Include your catalog in the same downstream views as extracted observations

Imports are not a separate product model. They are another way to create captures.

Creating an import

Dashboard

Navigate to Extract > Imports > New.

Choose a catalog file, confirm the country and language, then upload it. The import appears in Extract > Imports > List with its current status, success count, error count, and status message.

Supported source files currently include JSON, JSONL, and CSV. The file should contain enough product data to build valid captures: product titles, images, variants or SKUs, source prices, currency information where available, and stable source product identity.

API

The dashboard sends the file to the Extract API. API clients can use the same import endpoint under /v1/extract/imports.

Send the source file as the request body and metadata as query parameters:

curl -s -X POST \
  "https://api.extralt.com/v1/extract/imports?file_name=catalog.csv&country_code=US&language_code=en&source_host=shop.example" \
  -H "Authorization: Bearer $EXTRALT_API_KEY" \
  -H "Idempotency-Key: import-catalog-example-1" \
  -H "Content-Type: text/csv" \
  --data-binary @catalog.csv | jq

The response is 202 Accepted with { "id": "<import-id>" }. Poll GET /v1/extract/imports/{id}, then list Captures with GET /v1/extract/captures?import_id={id}. Retry an interrupted upload with the same file, metadata, and Idempotency-Key. Creating a new Import requires an active subscription; replaying a completed request with the same key still returns its original result.

Validation

Imports use the same capture quality gate as crawled data. Extralt does not force incomplete catalog rows into captures.

Each product must have at least one of:

• A full source product URL, such as https://shop.example/products/runner.
• A recognized global product ID. Currently supported: Shopify Product IDs in the form gid://shopify/Product/<positive integer>.
• A merchant-local product ID, such as 123, with a reliable Store host from the record or the Import's Default Store website (source_host in the API).

A product URL is optional when the ID identifies its source. Multiple variant rows may share their product's ID; variant identifiers remain optional. Titles and row numbers cannot substitute for product identity. These requirements apply both when preparing an Importer and whenever that Importer processes another file. Rejected records are excluded from Capture publication and identified in validation errors.

A namespace alone does not make an ID globally unique: values such as urn:catalog:123 still need a product URL or source/shop host. Shopify ProductVariant IDs identify variants and cannot substitute for their parent Product ID.

An import can fail validation when the source data is too sparse or ambiguous, for example:

• no usable product title
• no product image
• no variant or SKU structure
• no source selling price (an explicitly observed zero is valid)
• rows that cannot be mapped to stable products
• nested data where products, variants, prices, or stock cannot be joined safely

When validation fails, the import status includes a message explaining what was missing or invalid.

After import

Once an import completes, open Extract > Captures and filter by the import job. Imported captures can then be enriched like captures from a crawl run.

The downstream model is the same: