# Getting Started (non-Shopify stores)

BasketBooster Recommender adds AI product recommendations, typo-tolerant search,
search-by-photo, and Shop-the-Look to any online store. This guide is for
**WooCommerce and custom storefronts**. (Shopify merchants: install the
BasketBooster app from the Shopify App Store instead — it handles everything
below automatically.)

## What you need

- A BasketBooster account — register at <https://dashboard.basketbooster.eu/register>.
  Every new account starts a **14-day free trial, no credit card required**.
- Your **publishable key** (`pk_...`) — shown on the dashboard's
  *Recommender → Widget snippet* page. It is safe to put in storefront HTML.
- A **secret API key** (for catalog sync from your server) — create one on the
  dashboard's *API Keys* page. It is shown only once; store it server-side and
  never expose it in a browser.

## The 15-minute path

### 1. Connect your catalog

Pick one:

- **WooCommerce** — install the BasketBooster Recommender plugin, paste both
  keys in its settings, click *Sync now*. See [woocommerce-plugin](woocommerce-plugin.md).
- **CSV upload** — upload your product catalog on the dashboard's *Catalog* page.
- **REST API** — push products from your own backend with
  `POST /v1/items` (secret key auth). See [v1-api-reference](v1-api-reference.md).

Your search index and recommendation engines are provisioned automatically once
the first products arrive.

### 2. Drop in the widget

One script tag plus one custom element:

```html
<script src="https://api.basketbooster.eu/widget/v1/your-store.com.js" async></script>
<product-recs data-key="pk_YOUR_KEY" data-item-id="PRODUCT_ID"></product-recs>
```

That renders a "You may also like" grid on a product page. Cart pages, trending
feeds, search, and Shop-the-Look are the same pattern with different attributes —
see [widget-embed](widget-embed.md).

### 3. Send events (make it learn)

The widget tracks views, clicks, and impressions automatically. Your storefront
sends the two commerce events itself: **`add-to-cart`** from your cart handler
(`ProductRecs.track('add-to-cart', {item_id, value, currency})` — see
[widget-embed](widget-embed.md)) and a **purchase** event from your
order-confirmation page so the engine learns from real sales:

```html
<script>
  ProductRecs.track('buy', {
    item_id: 'PRODUCT_ID',
    user_id: 'CUSTOMER_ID',   // optional
    order_id: 'ORDER_1234',   // groups items bought together (FBT signal)
    value: 49.9,
    currency: 'EUR'
  });
</script>
```

Prefer server-side? Sync each new order from your **order webhook** instead —
one call with the whole basket, idempotent on retries:

```bash
curl -X POST "https://api.basketbooster.eu/v1/orders" \
  -H "X-API-Key: YOUR_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"order_id": "ORDER_1234", "user_id": "CUSTOMER_ID", "currency": "EUR",
       "items": [{"item_id": "PRODUCT_ID", "quantity": 1, "price": 49.9}]}'
```

Optionally, seed the Frequently-Bought-Together model with your **order
history**: upload a CSV
(`order_id,item_id[,customer_id][,timestamp][,quantity][,price]`) on the
dashboard or via `POST /orders/upload` (secret key auth). Columns are matched
by name in any order; `quantity` (units in the line) and `price` (unit price)
unlock unit-based demand forecasts and revenue predictions — re-uploads are
deduplicated, and lines that add quantity/price to already-imported orders
fill them in.

### 4. Theme it

Widget colors, fonts, and layout are configured on the dashboard's widget
designer — no CSS required, and changes go live immediately. Everything is
overridable with your own CSS if you prefer.

## What happens on day one

New stores start with bestseller/trending recommendations immediately and get
personal as shopper events flow in. Recommendations improve continuously; no
manual retraining is needed.

## Docs for your AI assistant

Working with Claude Code, Cursor, or another MCP-capable assistant? Point it at
our documentation server and it can read all of these guides while it writes
your integration:

```bash
claude mcp add --transport http basketbooster-docs https://api.basketbooster.eu/mcp
```

Or fetch plain-text docs directly: <https://api.basketbooster.eu/llms.txt>.

## Next steps

- [widget-embed](widget-embed.md) — every widget and attribute
- [v1-api-reference](v1-api-reference.md) — the full public API
- [publishable-keys-and-cors](publishable-keys-and-cors.md) — key types and origin allowlists
- [plans-and-billing](plans-and-billing.md) — trial, plans, quotas