Quickstart (5 min)

What you will do

This walkthrough is the shortest path through eListSync: one destination, one product, one publish. You will not configure every marketplace, write a transformer, or touch Redis. The goal is to prove the loop works on your machine: ingest once, fan out to a real (or lab) channel, and see a row in the sync log.

Hobby is enough. You do not need a credit card. The catalog, destinations hub, and publisher all live in the operator dashboard.

Prerequisites

• A browser on the same host as the Next.js app (default http://127.0.0.1:3000)
• For Shopify or Amazon: a sandbox / custom app you control (never paste production secrets into a shared demo)
• For Medusa / custom REST: a store that answers GET /health (the lab bridge on port 9000 is documented under MedusaJS)
• Optional: a public product URL with Schema.org JSON-LD so the scraper does not need DOM heuristics

If you only want to click through the UI, you can still connect Custom REST to the local Medusa bridge and ingest a sample URL.

1. Open the workspace

From the marketing site, choose **Start free — Hobby plan** or **Open dashboard**. That hits /api/auth/session?role=user&next=/dashboard and lands you in the operator shell.

The dashboard is scoped to your organization. Products, destination accounts, listings, and sync logs are tenant-isolated in Postgres (RLS). Do not expect to see another org's catalog.

2. Connect a destination

Open **Destinations** (/dashboard/destinations). Pick one channel you actually have credentials for:

• Shopify — OAuth against *.myshopify.com with write_products and inventory scopes
• Amazon — SP-API LWA; refresh tokens stored encrypted on destination_accounts
• TikTok Shop, eBay, Walmart — Seller / marketplace OAuth as documented on those pages
• WooCommerce — consumer key + secret against /wp-json/wc/v3
• Medusa / custom REST — Base API URL + Bearer token; eListSync health-checks before save

eListSync will not save a destination that fails health check. That is intentional: a dead Base URL should fail in Destinations, not later in a publish queue.

You only need **one** destination for this walkthrough. Hobby allows two connected channels.

3. Ingest a product

Open **Import** (/import). Paste a product URL and run preview, then **Sync to Database**.

What you should see in the catalog:

• One canonical product (title, brand, price, currency, images)
• Variants when the source page exposes Size×Color (or equivalent) with SKUs
• Metadata in ai_generated_metadata when enrichment ran (SEO rewrite, category hints)

Three ingest paths exist; pick one:

1. URL scraper — POST /api/import/url (JSON-LD first, DOM fallback)
2. Document — CSV / JSON / PDF at /import/document
3. Browser extension — POST /api/extension/ingest with x-toksync-api-key

If preview returns empty, read Troubleshooting (DOM timeouts, local ingest flag, missing JSON-LD). Do not publish an empty product.

4. Publish and verify

Open **Publisher** (/dashboard/products/publish). Select the product and the destination you connected. Click Publish.

Then open the product detail (or Destinations health):

• channel_listings should show a remote id or pending state
• channel_sync_logs should show success, retry, or a mapper/API error — never a silent catch

If the channel returns 429, that job backs off on **that** queue only. Other destinations keep running. If the SKU is rejected, the log names the field the transformer sent; fix the canonical variant and republish.

What happened under the hood

Ingest → Normalize (canonical product + variants) → transformForChannel → BullMQ bulkhead → channel API → listing + sync log

Secrets stay AES-GCM encrypted at rest. Publish jobs do not share a single global queue: Shopify traffic cannot starve Amazon. Inventory webhooks (when the channel supports them) later decrement stock through Redis Lua locks so two marketplaces cannot oversell the same unit.

Next steps

• Connect a second destination and publish the same SKU — that is the product, not a second listing team
• Read Architecture for route groups, Postgres tables, and Redis roles
• Read the channel guide for the marketplace you connected (scopes, payloads, common errors)
• Use the ROI calculator on the marketing site only after you select at least one real platform