O
OnFitt/ Docs← App
SDK v1 · REST API v1

OnFitt SDK & API Reference

Add a virtual try-on button to any product page in one line of HTML. Customers upload a photo and see themselves wearing your product — powered by generative AI.

#Quick start

Paste one <script> tag on your product page. The SDK auto-detects your product image and injects a "Try this on" button beneath it.

<script
  src="https://getonfitt.com/sdk.js"
  data-api-key="sk_live_YOUR_KEY">
</script>
Required: Replace sk_live_YOUR_KEY with your API key from the dashboard.

#Product image detection

The SDK resolves the clothing item to send to the AI in this order of priority:

  1. Explicit URL list — data-clothing-urls
  2. Gallery selector — data-product-images (CSS selector for <img> tags)
  3. og:image meta tag — automatic, no configuration needed

Multi-image gallery (best results — AI picks the best angle):

<script
  src="https://getonfitt.com/sdk.js"
  data-api-key="sk_live_..."
  data-product-images=".product-gallery img">
</script>

Explicit URL list (JSON array):

data-clothing-urls='["https://yourstore.com/jacket-front.jpg","https://yourstore.com/jacket-side.jpg"]'
If no product image is found the button is silently hidden and a warning is logged to the console.

#CTA button

Customize the injected button with data-* attributes or via the Dashboard → Customize panel. Script-tag attributes always take precedence over dashboard settings.

Themes

Four built-in themes — or go fully custom with your own hex.

Try this on
purple
Try this on
dark
Try this on
light
custom
custom

Button attributes

AttributeTypeDefaultDescription
data-api-keystring—Your OnFitt API key. Required.
data-themepurple | dark | light | custompurpleBuilt-in colour preset. Use custom to set your own colour via data-color.
data-colorhex / cssButton background when theme=custom.
data-text-colorhex / cssButton label colour when theme=custom.
data-radiusnumber (px)10Border radius of the button in pixels. 0–20.
data-button-labelstringTry this onLabel shown on the injected button.
data-attach-toCSS selectorIf set, the button is injected after the matched element instead of after the script tag.
<script
  src="https://getonfitt.com/sdk.js"
  data-api-key="sk_live_..."
  data-theme="custom"
  data-color="#e11d48"
  data-text-color="#ffffff"
  data-radius="8"
  data-button-label="See it on me">
</script>

#Modal theming

The try-on modal inherits your brand colours. Every attribute below can also be set permanently through the Dashboard without touching code.

AttributeTypeDefaultDescription
data-accent-colorhex#7c3aedPrimary action colour — drives the upload CTA, spinner, share button, and upload zone border.
data-modal-bghex#ffffffModal card background colour.
data-modal-title-colorhex#111111Colour of the modal title text ("Virtual Try-On" / "Your look").
data-close-icon-colorhex#9ca3afColour of the ✕ close button icon.
data-divider-colorhex / transparenttransparentColour of the horizontal line separating the modal header from the body. Set to transparent to hide.
data-powered-by-colorhex#9ca3afThe "Powered by" prefix text colour. The "OnFitt" brand name always stays in accent colour.

Dark modal example:

<script
  src="https://getonfitt.com/sdk.js"
  data-api-key="sk_live_..."
  data-theme="dark"
  data-accent-color="#f59e0b"
  data-modal-bg="#18181b"
  data-modal-title-color="#ffffff"
  data-close-icon-color="#71717a"
  data-divider-color="#27272a"
  data-powered-by-color="#52525b">
</script>

#Share

After a successful try-on, a Share your look button appears. On mobile it triggers the native share sheet; on desktop it shows a copy-link popover. Configure what gets shared:

AttributeTypeDefaultDescription
data-share-urlURLThe URL shared when a shopper taps Share. Typically your product page or brand homepage. If empty, the Share button is hidden.
data-share-messagestringCheck out my look!The message text included in the share payload (mobile share sheet).
data-share-url="https://yourstore.com/products/classic-jacket"
data-share-message="I just tried this on with OnFitt — check it out!"

#Dashboard-driven config

Every attribute above can be set once in the Dashboard → Customize panel and applied globally — no code changes needed. The SDK fetches your saved config on init and caches it for 1 hour.

CTA Button

  • •Theme (purple / dark / light / custom)
  • •Custom colour + text colour
  • •Border radius
  • •Button label

Modal

  • •Accent colour (spinner, CTAs, upload border)
  • •Modal background
  • •Title colour
  • •Close icon colour
  • •Divider line colour
  • •"Powered by" text colour

Share

  • •Share URL
  • •Share message

Priority

  • •Script-tag attributes always override dashboard settings
  • •Dashboard settings fill any attributes not specified in the tag
  • •Cached locally for 1 h (key: onfitt_cfg_{last8})

#JavaScript API

Once the SDK script is loaded, window.OnFitt exposes two methods.

OnFitt.open(cfg)

Opens the try-on modal programmatically. Useful for custom button placements or testing.

OptionTypeDescription
apiKeystringRequired. Your OnFitt API key.
_clothingUrlsstring[]Array of product image URLs to try on.
theme / accentColor / modalBg / …stringAny of the theming options listed above.
// Open the modal with a specific product image
window.OnFitt.open({
  apiKey: "sk_live_...",
  _clothingUrls: ["https://yourstore.com/jacket.jpg"],
  accentColor: "#e11d48",
  modalBg: "#18181b",
  modalTitleColor: "#ffffff",
  shareUrl: "https://yourstore.com/products/jacket",
});

OnFitt.init(cfg)

Runs the full init flow (usage check → remote config fetch → button injection). Use this when loading the SDK dynamically.

const s = document.createElement("script");
s.src = "https://getonfitt.com/sdk.js";
s.onload = () => window.OnFitt.init({
  apiKey: "sk_live_...",
  clothingUrls: ["https://yourstore.com/jacket.jpg"],
});
document.head.appendChild(s);

#REST API reference

Full OpenAPI spec — authenticate with your API key as Authorization: Bearer sk_live_....