Developer documentation

WardrobeIt technical overview for merchants and integrators.

Architecture, Shopify setup, merchant portal controls, storefront widget embed, shopper journeys, and the public plugin API — compiled from the shipping product (August 2026).

AudienceMerchants, agencies, evaluators
PlatformShopify now · WooCommerce planned
SurfacesWidget · Portal · Plugin API

Start with Shopify setup View plugin API Help Center

Overview

What WardrobeIt is — and what shoppers experience

A B2B AI stylist embedded on the merchant’s Shopify storefront. Shoppers stay on the brand site; catalog, checkout, and customer relationships stay with the merchant.

Three product jobs

Stylist chat

Natural-language discovery against this catalog only — occasion, budget, style, or size.

Catalog search

Fast structured search over synced inventory. No cross-store mash-ups or invented SKUs.

Virtual try-on

Eligible Growth+ previews with guided capture — QR on desktop, camera on mobile. Not a fit guarantee.

Typical shopper journeys

01
Discover
Describe a need; assistant may clarify, then shows in-catalog products.
02
This product
On a PDP, sizing and try-on refer to the garment on the page.
03
Try on
Capture → confirm → preview → note, cart, or alternatives.
04
Complete the look
Multi-product cards from the same store when a hero item is in focus.
05
Buy
Add to cart and checkout remain on Shopify. WardrobeIt does not process cards.

Architecture

Three components, one tenant per Shopify store

The shopper browser talks to WardrobeIt’s plugin API with a storefront key, and to Shopify cart endpoints on the store origin — never directly to Shopify Admin.

Layer	Role	User
Storefront widget	React in Shadow DOM · `wardrobeit-widget.js`	Shoppers
Merchant portal	Connect, sync, appearance, try-on, analytics, billing	Brand / ops
API gateway	Auth, search, try-on jobs, keys, metering, Stripe	Widget + portal
Catalog store	PostgreSQL per store · Redis for jobs/sessions	API only
Shopify	OAuth, Admin API, webhooks, `/cart/add.js`	Merchant + shopper

Capabilities

Live in production vs portal preview

Do not sell coming-soon portal screens as shipped capabilities. Plan limits and prices are API-backed — see Pricing.

Live Production today

Overview, store health, usage meters
Revenue & attribution (with approved order webhooks)
Assistant control — color, logo, launcher, Classic / Studio skin
Message manager — per-page greetings and starter chips
Virtual try-on — SKU enablement, consent, retention copy
Connections & catalog — OAuth, sync, plugin keys, merchant brief
Multi-store, session analytics, billing & usage

Coming soon Portal preview only

Executive reports, recommendation rules, offers & coupons
Leads & audiences, support handoff, multichannel marketing
Product intelligence, ops AI recommendations
Team permissions, agency white-label
WooCommerce connector stub

Setup & embed

Install on Shopify and embed the widget

Preferred path: OAuth from the merchant portal, then enable the theme app embed. Liquid snippet is the documented fallback.

OAuth path (recommended)

Portal → Connections & Catalog → Install on Shopify.
Enter brand.myshopify.com and approve the app.
Copy widget key ss_live_… when shown (once).
Theme Editor → App embeds → enable WardrobeIt stylist.
Paste API key, base URL, script URL. Test message + product card on storefront.

Custom app token fallback: Admin token with read_products + read_content.

Embed attributes

data-api-keyRequired · ss_live_…

data-api-baseRequired · …/api/v1

data-page-typehome · product · collection · cart

data-product-idCatalog UUID on PDP

Liquid — product page

{% if template.name == 'product' %}
<script src="https://YOUR_HOST/static/wardrobeit-widget.js"
  data-api-key="ss_live_…"
  data-api-base="https://YOUR_HOST/api/v1"
  data-page-type="product"
  data-product-id="{{ product.metafields.wardrobeit.id }}"
  defer></script>
{% endif %}

Try-on capture

Desktop — QR to phone; optional upload on device.
Mobile — camera capture; QR for another device.

Connect guide Install widget Theme embed

Portal & catalog

Merchant portal surfaces and catalog sync

The portal is the control plane for widget behavior, VTO policy, and Shopify catalog ingestion. API keys and OAuth tokens stay server-side.

Portal modules (live)

Overview — health, sync status, quick actions
Assistant — branding, launcher, Classic / Studio
Messages — page-type greetings and chips
Try-on — SKU toggles, consent, retention
Connections — Shopify OAuth, plugin keys
Catalog — sync jobs, metafield mapping

Catalog pipeline

OAuth or custom app token registers the store.
Background sync pulls products, variants, images, tags.
Metafield wardrobeit.id maps Shopify → catalog UUID.
Widget passes data-product-id on PDP for context.
Re-sync on demand from Connections & Catalog.

VTO eligibility is per-SKU in portal — not every product is try-on ready on day one.

Merchant portal product page API keys Catalog sync guide

API & FAQ

REST surface, auth, and common questions

Public widget traffic uses store-scoped keys. Server integrations use merchant API keys with tighter scopes — rotate from the portal.

Auth model

Key type	Prefix	Used by
Widget (public)	`ss_live_`	Storefront script embed
Merchant API	`sk_live_`	Server-side integrations

Representative endpoints

Method	Path	Purpose
POST	`/sessions`	Start shopper session
POST	`/messages`	Assistant chat turn
GET	`/products/{id}`	Catalog context for PDP
POST	`/try-on`	Initiate VTO capture
POST	`/webhooks/orders`	Attribution (merchant setup)

Full OpenAPI reference ships with merchant onboarding. Do not expose sk_live_ keys in theme Liquid.

Frequently asked

Can I run the widget without Shopify OAuth?

Yes — custom app token + manual catalog sync is supported, but OAuth is the supported merchant path.

Where do product UUIDs come from?

Catalog sync writes wardrobeit.id metafields. Reference them in Liquid for data-product-id.

Is try-on available on every SKU?

No — merchants enable eligible SKUs in the portal. The widget hides try-on when a SKU is not enabled.

How do I test before go-live?

Use a development store, enable the theme embed, and verify assistant + product cards on PDP and collection pages.

Ready to integrate?

Book a technical walkthrough or start a trial — we will validate OAuth, embed, and catalog mapping with your theme.

Book a Demo Start Free Trial API keys