Headless quickstart
Add profile-driven product matching to any storefront — Shopify headless, commercetools, custom React, plain HTML. One script tag. No build step required.
Issue a read-only shopper token for your merchant. This token identifies your store and is safe to embed in a public script tag — it only has read scope.
curl -X POST https://api.fewture.com/v1/merchants/me/tokens \
-H "x-merchant-id: YOUR_MERCHANT_ID" \
-H "Content-Type: application/json" \
-d '{"scopes": ["read"]}'{
"token": "fwtok_a1b2c3...",
"scopes": ["read"],
"createdAt": "2026-05-18T00:00:00.000Z"
}Save the token value — you'll use it in the script tag below. Tokens don't expire by default. Rotate them via the same endpoint and update your script tag.
Testing locally?
The demo merchant ships with a pre-seeded token: fwtok_demo_public_readonly. Point data-api-url at http://localhost:3051 to use it.
Place an empty <div> where you want the Fewture widget to appear — in your product page template, cart sidebar, or checkout flow.
<div id="fewture-app"></div>
The ID must match the data-container attribute on the script tag. The widget renders into a Shadow DOM root, so your page styles won't bleed in.
Add the script tag after your mount container. The SDK auto-mounts on DOMContentLoaded.
<script src="https://cdn.fewture.com/sdk/fewture-sdk-v0.1.0.js" data-merchant-id="YOUR_MERCHANT_ID" data-token="fwtok_a1b2c3..." data-api-url="https://api.fewture.com" data-vertical="pet" data-container="fewture-app" ></script>
| Attribute | Required | Description |
|---|---|---|
| data-merchant-id | yes | Your merchant ID. Used as fallback if token lookup fails. |
| data-token | yes | Bearer token issued in step 1. Sent as Authorization header on all API calls. |
| data-api-url | yes | Base URL of the Fewture API. Omit trailing slash. |
| data-vertical | no | Schema vertical to use. Defaults to "pet". |
| data-container | no | ID of the mount element. Defaults to "fewture-app". |
Open the live test page — it loads the versioned SDK bundle against your local API with the demo merchant token.
# Start the stack if it isn't already running pnpm run bootstrap # postgres + redis pnpm run seed # demo merchant + 277 products pnpm --filter api run start pnpm --filter web run dev # Then open in your browser: open http://localhost:3050/sdk/demo.html
You should see the three-screen widget: pet profile form → curated basket → confirm. If the basket is empty, check that pet_species is included in your profile — it's the primary exclude rule.
The widget reads your merchant's branding tokens at mount time and applies them as CSS custom properties. Update them via the Brand Studio or API — no redeployment needed.
curl -X PATCH https://api.fewture.com/v1/merchants/me/branding \
-H "x-merchant-id: YOUR_MERCHANT_ID" \
-H "Content-Type: application/json" \
-d '{
"primaryColor": "#6366f1",
"secondaryColor": "#1e1b4b",
"fontFamily": "Inter",
"borderRadius": 12,
"buttonStyle": "filled"
}'Or use the Brand Studio for a live preview before saving.
All endpoints are prefixed with /v1. Pass Authorization: Bearer <token> or x-merchant-id on authenticated calls.
/v1/schemas/:verticalFetch the rule schema for a vertical (pet, beauty, …)/v1/matchRun profile → basket matching. Returns basket + explanation trace./v1/match/:id/feedbackRecord accept / edit / abandon signal on a match result./v1/merchants/meFetch your merchant record including branding tokens./v1/merchants/me/brandingPublic — returns CSS variable map. Used by SDK at mount./v1/merchants/me/brandingUpdate branding tokens. Invalidates the Redis cache./v1/merchants/me/tokensIssue a new scoped API token./v1/catalogue/syncBulk upsert products for this merchant./v1/catalogue/productsUpsert a single product./v1/catalogue/products/:skuRemove a product from the catalogue./v1/profilesCreate or update a shopper profile./v1/profiles/:shopperIdFetch a saved shopper profile.