Imports API

REST API endpoints for importing catalog content from external stores.

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

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)

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

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

Response (200)

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

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

Response (200)

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

PreviousMediaAPI Reference NextImagesAPI Reference