Import products from an external store (Shopify, WooCommerce, or any product page) into your YNS store. Imports run asynchronously – start a job and poll for progress.

## Start Import

```
POST /api/v1/imports
```

Starts an asynchronous catalog import. Returns a `jobId` immediately (HTTP 202) – poll `GET /api/v1/imports/{jobId}` for progress and results.

Shopify stores are imported at full fidelity (images, descriptions, SKUs). WooCommerce and other platforms fall back to best-effort extraction. Each product is created as a single default variant. Items are created as `draft` by default so you can review before publishing. Existing slugs are skipped, so re-running is safe.

### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `sourceUrl` | `string` | Yes | – | The source store URL (Shopify, WooCommerce, or any product page) |
| `type` | `string` | No | `"products"` | What to import. Currently `products` only. |
| `status` | `string` | No | `"draft"` | Status for imported items: `"draft"` or `"published"` |

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://example-store.myshopify.com",
    "status": "draft"
  }' \
  https://your-store.yns.store/api/v1/imports
```

### Response (202)

```json
{
  "message": "Import started",
  "jobId": "0191abc0-1234-7def-8000-000000000001",
  "type": "products",
  "stage": "scraping",
  "sourceUrl": "https://example-store.myshopify.com"
}
```

---

## Get Import Job

```
GET /api/v1/imports/{jobId}
```

Returns a single import job by UUID. Use this to poll for progress after starting an import.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `jobId` | `string` | Import job UUID |

```bash
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/imports/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "type": "products",
  "sourceUrl": "https://example-store.myshopify.com",
  "stage": "completed",
  "error": null,
  "metadata": {
    "platform": "shopify",
    "currency": "USD",
    "detectedCount": 25,
    "imported": 23,
    "skipped": 2,
    "errors": []
  },
  "createdAt": "2026-07-01T10:00:00.000Z",
  "updatedAt": "2026-07-01T10:02:30.000Z",
  "completedAt": "2026-07-01T10:02:30.000Z"
}
```

### Job Stages

| Stage | Description |
|-------|-------------|
| `scraping` | Fetching product data from the source URL |
| `importing` | Creating products in the store |
| `completed` | Import finished successfully |
| `failed` | Import failed – check the `error` field |

### Metadata Fields

Once the job progresses past `scraping`, the `metadata` object contains:

| Field | Type | Description |
|-------|------|-------------|
| `platform` | `string` | Detected platform: `"shopify"`, `"woocommerce"`, or `"generic"` |
| `currency` | `string \| null` | Source store currency |
| `detectedCount` | `number` | Number of products found at the source |
| `imported` | `number` | Products successfully created |
| `skipped` | `number` | Products skipped (e.g. duplicate slugs) |
| `errors` | `object[]` | Per-product errors: `{ name, error }` |

---

## List Import Jobs

```
GET /api/v1/imports
```

Returns this store's import jobs, newest first.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 20 | Jobs per page (1-100) |
| `offset` | `number` | 0 | Number of jobs to skip |

```bash
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/imports
```

### Response (200)

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "type": "products",
      "sourceUrl": "https://example-store.myshopify.com",
      "stage": "completed",
      "error": null,
      "metadata": {
        "platform": "shopify",
        "detectedCount": 25,
        "imported": 23,
        "skipped": 2,
        "errors": []
      },
      "createdAt": "2026-07-01T10:00:00.000Z",
      "updatedAt": "2026-07-01T10:02:30.000Z",
      "completedAt": "2026-07-01T10:02:30.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 20
  }
}
```