Start here

Quickstart

From a fresh sign-up to a tracked storefront, an imported catalogue, personalised recommendations and a live quote. About an hour of work, most of it waiting for a CSV export.

You need: an email address, a CSV of your products, and the ability to paste a script tag into your website template. Everything else is optional and can wait.

Create an account

Sign up at /signup. You give a name, an email and a password of at least eight characters, and you land on the onboarding screen.

The same thing over the API:
```
curl -X POST https://app.stitchwork.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","password":"correct-horse"}'
```
The response sets a session cookie and returns {"data":{"user":…,"next":"/onboarding"}}. Keep the cookie jar — the whole session API uses it.
Name your workspace

One field. Naming the workspace creates your organisation, starts a 7-day free trial, and spins up a default channel called Website so you have somewhere to hang quotes and events from day one.
```
curl -X POST https://app.stitchwork.io/api/v1/organizations \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"name":"Maison Aurelia"}'
```
There is no billing step. Accounts are sold by hand, so terms are agreed with us rather than picked from a page — see Your 7-day trial.
Describe where you sell

A channel is a surface you sell through: your website, a specific store, a kiosk, a pop-up, a marketplace listing. You already have Website. Add one channel per physical location you want to attribute in-store activity to.
```
curl -X POST https://app.stitchwork.io/api/v1/channels \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{
    "name": "Mayfair",
    "type": "store",
    "ownership": "owned",
    "city": "London",
    "country": "GB",
    "currency": "GBP",
    "timezone": "Europe/London"
  }'
```
Set your website channel's url under Channels → Website → Settings. It is what channel-entry QR codes point at, and it lets bare page views be attributed to the web channel.

Load your catalogue

Export products from your commerce platform as CSV and drop it on Products → Import. The importer accepts Shopify- and Magento-shaped exports; the only column it truly needs is a SKU.

The single most valuable column is web_url (aliases: url, product_url). It is how a page view on your site becomes a product view in Stitchwork. Second most valuable is category — it drives category interest and category balancing.

product_sku,product_name,product_type,brand,category,base_price,currency,status,web_url,variant_sku,variant_price,option:wood,option:size
CONCERTO,Concerto Acoustic,configurable,Maison Aurelia,Acoustic guitars,2500,GBP,active,https://example.com/guitars/concerto,CONCERTO-MAH-O,2500.00,mahogany,O
CONCERTO,Concerto Acoustic,configurable,Maison Aurelia,Acoustic guitars,2500,GBP,active,https://example.com/guitars/concerto,CONCERTO-MAH-OO,2600.00,mahogany,OO
SKETCHPAD,Sketchpad No.3,simple,Maison Aurelia,Stationery,45,GBP,active,https://example.com/paper/sketchpad-3,SKETCHPAD,45.00,,

Or over the API:

curl -X POST https://app.stitchwork.io/api/v1/products/import \
  -b cookies.txt -F "file=@catalogue.csv"

Re-running the same file is safe: rows are matched on SKU and updated in place. See Importing a catalogue for every column the importer understands.

Import your sales history

Optional, but it is what makes recommendations useful on day one rather than day thirty. Export the last year or two of orders as a Shopify-style CSV — one row per line item — and drop it on Orders → Import.
```
order_number,email,customer_name,sku,quantity,unit_price,line_total,placed_at,channel
1001,eleanor@example.co.uk,Eleanor Vance,CONCERTO-MAH-OO,1,2600.00,2600.00,2025-11-04,Website
1002,marcus@example.com,Marcus Pemberton,SKETCHPAD,3,45.00,135.00,2025-11-06,Mayfair
```
Customers are upserted by email as they go, so this step also seeds your CRM. The import auto-triggers a ranking recompute when it finishes, so the bestseller signal is live immediately.
Generate your tracking keys

Go to Settings → Web tracking and click generate. You get two keys and the second one is shown exactly once:

pk_live_…

Public write key. Safe in browser JavaScript. Only accepted on event ingest and the read-only public endpoints.

sk_live_…

Secret bearer. Server-side only. Stored hashed — we cannot show it to you again, only replace it.

Copy the secret now
There is no endpoint that reads a secret key back. If you lose it, rotate — which invalidates the old one everywhere it is in use.
Install the tag

Paste this into your site template, on every page. The first line is a stub so sw(…) is callable immediately — calls made before the deferred tag finishes loading are queued and replayed.
```
<script>window.sw=window.sw||function(){(window.sw.q=window.sw.q||[]).push(arguments)};</script>
<script defer src="https://app.stitchwork.io/tag/your-workspace-slug.js"></script>
```
The exact URL, with your slug already in it, is on the settings page. Page views track automatically, including single-page-app navigations. Everything else you fire yourself:
```
sw('track', 'view_product', { sku: 'CONCERTO-MAH-OO' });
sw('track', 'add_to_cart',  { sku: 'CONCERTO-MAH-OO', price: 2600, currency: 'GBP' });
sw('track', 'search',       { query: 'walnut concerto' });
sw('track', 'purchase',     { order_id: '1001', value: 2600, currency: 'GBP' });
```
Always send a SKU
view_product, add_to_cart and purchase tie to a product through props.sku — parent or variant, either works. A bare page view can fall back to matching the URL against products.web_url, but nothing else does.

Consent defaults to auto: Cookiebot, Shopify Customer Privacy and IAB TCF v2.2 are detected automatically, and Global Privacy Control is honoured as a hard floor. See Consent and CMPs before you ship to a GDPR audience.

Check that events are arriving

Load a product page on your site, then open Rankings in the app. The Popular input count should move. Or open a customer you know has browsed and look at their activity timeline.

You can also fire an event by hand:

curl -X POST https://app.stitchwork.io/api/v1/track/event \
  -H "Authorization: Public pk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "visitor_token": "test-visitor-0001",
    "type": "view_product",
    "url": "https://example.com/guitars/concerto",
    "props": {"sku": "CONCERTO-MAH-OO"}
  }'

A 204 No Content means it landed.

Build and send a quote

Open Quotes → New, pick a customer, and start adding lines. If the customer has browsing history, it is inlined right there with add-to-quote buttons, and the recommendations panel is personalised to them.

Same thing over the API:

curl -X POST https://app.stitchwork.io/api/v1/quotes \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{
    "channel_id": 2,
    "customer_id": 14,
    "currency": "GBP",
    "tax_rate": 20,
    "tax_inclusive": true,
    "line_items": [
      {"sku":"CONCERTO-MAH-OO","description":"Concerto in mahogany, OO","quantity":1,"unit_price":"2600.00"}
    ]
  }'

# then send it — the customer gets a link by email
curl -X POST https://app.stitchwork.io/api/v1/quotes/7/send -b cookies.txt

The customer opens /q/{token} on their phone and can accept, decline, pay by card (if you have connected Stripe), or bounce to your own checkout.

Put personalisation on your site

The fastest version is one tag:
```
<script src="https://app.stitchwork.io/assets/embed/sw-recs.js" defer></script>

<sw-recs key="pk_live_xxxxxxxxxxxx" limit="6"></sw-recs>
```
It reads the __sw_v cookie the tag already set, renders in shadow DOM so it cannot collide with your CSS, and falls back to global top-rank for a first-time visitor. For re-ordering your own category grids instead, see Re-ranking category pages.

What to do next

In rough order of payoff:

Next step	Why it's worth it	Where
Tune the ranking	The defaults are deliberately neutral. Five minutes on the sliders usually moves recommendations from plausible to obviously right.	Tuning
Print store QR codes	Turns a physical visit into a tracked, attributed session — and puts store visits on the customer's timeline next to their browsing.	QR attribution
Add the join endpoint	One small route on your domain. It is what lets an agent's QR stitch an anonymous browser to the customer in front of them.	Join endpoint
Invite your team	Store staff get channel-scoped access — they can run quotes without touching the catalogue or settings.	Inviting people
Subscribe a webhook	Push quote and order changes into your OMS instead of polling.	Webhooks
Connect Stripe	Lets customers pay a quote from their phone, settling to your own Stripe account.	Taking payment

Stuck?

Troubleshooting covers the failure modes that actually happen — empty recommendation lists, unmatched SKUs, a tag that fires but records nothing, and what each HTTP status code is really telling you.

Quickstart

Create an account

Name your workspace

Describe where you sell

Load your catalogue

Import your sales history

Generate your tracking keys

Install the tag

Check that events are arriving

Build and send a quote

Put personalisation on your site

What to do next