Help
Glossary
Every Stitchwork term, cookie, key prefix and status value, alphabetically.
Terms
- access state
- Whether a workspace may be used:
trial,active,suspendedorclosed. Operator intent, evaluated on every request. See access. - affinity
- A per-customer, per-product counter of views, cart adds and quote appearances. It is what makes recommendations personal.
- attribution snapshot
- A frozen copy of a visitor's ad-touch trail —
{first_touch, last_touch, touch_count}— stamped onto a quote or an order at creation, so the conversion keeps its source even if identity is later reassigned. - bestseller window
- How far back sales count towards the bestseller signal. 365 days by default.
- category balance
- A 0–1 dial that interleaves recommendation output across categories. 0 is pure relevance; 1 is strict round-robin.
- channel
- A surface you sell through: website, store, kiosk, pop-up, marketplace, wholesale. Quotes and orders both belong to one.
- channel role
- Per-channel permission:
admin,managerorassociate. Independent of the workspace role. - configurable product
- A product with option axes, whose variants are generated from their cartesian product.
- conversion window
- How far before a conversion an ad touch can sit and still get credit. 90 days by default, 1–365 allowed.
- delivery
- One attempt-tracked row pairing a webhook event with a subscription. Statuses:
pending,succeeded,failed,dead. - event
- One recorded action by a visitor: a page view, product view, cart add, search, purchase, QR scan or campaign arrival.
- featured
- A manual per-product flag that lifts it in the ranking. Weighted at 2.0 by default and applied outside the personalisation blend, so it lifts for everyone.
- join code
- A single-use, five-minute code minted by a public quote page so a customer's phone can be linked to their customer record through your join endpoint.
- join endpoint
- A route on your domain that reads the
__sw_vcookie and posts it to Stitchwork with a join code. The only place that cookie is readable. - line item
- One row on a quote or an order. Snapshots its description, SKU and unit price, so later catalogue edits never rewrite a sent quote.
- option
- An axis of choice on a configurable product —
wood,size,colour. 1–40 lowercase letters, digits or underscores. - organisation
- One brand's workspace. The isolation boundary — everything else hangs off it.
- owner
- The user who created the workspace. Exactly one, and the only role that can edit the catalogue, run imports, delete records or set up payments.
- personalisation strength
- A 0–1 dial blending global ranking against the per-customer overlay. 0.5 by default.
- public token
- A 32-character unguessable string on every quote. It is the authentication for
/q/{token}. - quote
- A proposal: channel, customer, lines, totals, and a link only the customer has.
- recompute
- Rebuilding the materialised global ranking signals. Triggered by hand, or automatically after an order import.
- row-level security
- PostgreSQL policies that reject rows belonging to another workspace, layered underneath the explicit filters in application code.
- signal
- One input to the ranking score. Seven global (bestseller, popular, carted, newness, featured, price target, on sale) and three personal (view, cart, quote).
- simple product
- One thing, one price. Gets exactly one auto-created variant, so every product has at least one.
- SKU
- The join key between your systems and Stitchwork. Matched against product SKUs first, then variant SKUs; a variant SKU always rolls up to its parent as well.
- slug
- A URL-safe workspace identifier, used in the tracking tag URL. Never changes when you rename the workspace.
- stitching
- Linking an anonymous visitor to a named customer, which retroactively attributes their entire browsing history.
- subscription
- A webhook destination: one URL, one event filter, one signing secret.
- tax inclusive
- Quote mode where line prices already contain tax. The total equals the discounted subtotal; the tax figure is informational.
- touch
- One recorded ad arrival — UTM parameters or a click id — against a visitor.
- variant
- A specific purchasable combination of a product's options, with its own SKU, price and status. What quote and order lines point at.
- visitor
- One anonymous browser, identified by the
__sw_vcookie. Becomes a known person when linked to a customer. - workspace role
owner,adminormember. Separate from channel roles.
Key and id prefixes
| Prefix | What it is | Where it goes |
|---|---|---|
pk_live_ | Public tracking key | Browser. Authorization: Public …, or ?key= on public read endpoints. |
sk_live_ | Secret tracking key | Your server only. Authorization: Bearer …. |
whsec_ | Webhook signing secret | Your webhook receiver. Shown once at creation and once per rotation. |
evt_ | Webhook event id | The envelope's id and the Stitchwork-Event-Id header. Dedupe on this. |
Q-YYYY-NNNNNN | Quote number | Human-facing. Unique per workspace per year. |
acct_ | Stripe Connect account | The merchant's own Stripe Express account. |
Cookies
| Name | Set by | Lifetime | Purpose |
|---|---|---|---|
__sw_v | The tag | 2 years, sliding | Visitor identity on your domain. Written only after consent. |
__sw_channel | The tag | 30 min, sliding | Physical-channel attribution after a QR scan. |
__sw_attr | The tag | 30 min, sliding | Deduplicates campaign touches. |
| PHP session | The app | 14 days | Staff authentication on the Stitchwork app itself. HttpOnly, SameSite=Lax. |
URL markers
| Parameter | Meaning | Stripped? |
|---|---|---|
_sw_ch | Channel id this scan belongs to. | Yes |
_sw_scan | Marks the arrival as a QR scan. | Yes |
_sw_qr | Which specific QR code was scanned. | Yes |
utm_*, gclid, fbclid, msclkid | Campaign attribution. | No — your own analytics need them |
joined, reason | Result of a QR join, on the return to the quote page. | No |
Status values
| Where | Values |
|---|---|
| Workspace access | trial, active, suspended, closed |
| Workspace role | owner, admin, member |
| Channel role | admin, manager, associate |
| Channel type | web, store, marketplace, kiosk, pop_up, wholesale |
| Channel ownership | owned, franchise, authorised, wholesale, marketplace |
| Channel status | active, paused, closed |
| Product type | simple, variant, configurable |
| Product / variant status | draft, active, discontinued |
| Quote status | draft, sent, accepted, declined, expired, cancelled, paid |
| Quote discount type | amount, percent |
| Quote origin | app, external |
| Order status | paid, refunded, cancelled, fulfilled |
| Order origin | app, import, quote_conversion, external |
| QR kind | product, channel_entry, custom |
| Event type | page_view, click, search, add_to_cart, view_product, purchase, qr_scan, campaign_touch, scroll_depth, custom |
| Consent mode | auto, require, off |
| Attribution model | time_decay, linear, position_based, last_touch, first_touch |
| Webhook delivery | pending, succeeded, failed, dead |
Headers
| Header | Direction | Purpose |
|---|---|---|
Authorization: Public pk_live_… | To Stitchwork | Storefront / browser calls. |
Authorization: Bearer sk_live_… | To Stitchwork | Server-to-server calls. |
X-Migrate-Token | To Stitchwork | Migration endpoint. |
X-Admin-Key | To Stitchwork | Ops endpoints. |
Stitchwork-Signature | From Stitchwork | t=<unix>,v1=<hex hmac-sha256>. |
Stitchwork-Event-Id | From Stitchwork | Dedupe key for webhook deliveries. |
Stitchwork-Event | From Stitchwork | Event type, for routing before parsing. |
Stitchwork-Attempt | From Stitchwork | 1-based attempt number. |