Skip to main content

​
Script Setup

<script
  src="https://hemsy.ai/hemsy-embed.js"
  data-hemsy-subdomain="your-store-subdomain"
  data-hemsy-closet-selector="#open-hemsy"
  data-hemsy-auto-product-context="false"
  defer
></script>

​
Required Attributes

  • data-hemsy-subdomain: Your configured Hemsy store subdomain. You can find it in your store’s Hemsy Merchant Dashboard under Settings.

​
Selector Requirement

Provide at least one selector attribute on the script:
  • data-hemsy-closet-selector: CSS selector for element(s) that should open Hemsy in closet mode.
  • data-hemsy-scratch-selector: Selector for opening Hemsy in scratch mode.
You can provide both if you support both entry points.

​
Important for Bundles

Set data-hemsy-auto-product-context="false" when passing a custom closet payload. If set to "true", Hemsy can replace your provided closet payload with current PDP context. In other words, we’ll detect the shoppers currently selected variant on your PDP page.

​
Data Attributes Reference

​
Script Attributes

AttributeRequiredExampleDescription
data-hemsy-subdomaintruemystoreYour Hemsy store subdomain: For mystore.hemsy.ai -> “mystore” is your subdomain.
data-hemsy-closet-selectorfalse"#open-hemsy"CSS selector for elements that open Hemsy in closet mode.
data-hemsy-scratch-selectorfalse".open-hemsy-scratch"CSS selector for elements that open Hemsy in scratch mode.
data-hemsy-auto-product-contextfalse"false"If true, closet opens can auto-use current PDP product context. Use false for explicit closet payloads.
data-hemsy-close-on-escapefalse"true"Enable/disable close on Esc. Default: true.
data-hemsy-close-on-backdropfalse"true"Enable/disable close when backdrop is clicked. Default: true.

​
Trigger Attributes

AttributeExampleDescription
data-hemsy-trigger"closet"Trigger mode. Supported values: closet, scratch.
data-hemsy-closet"eyJwcm9k..."URL-safe base64 closet payload. Note: Required for closet payload launches.
If you use data-hemsy-closet-selector, data-hemsy-trigger is optional on that same element because selector binding already opens closet mode.

​
Open Hemsy with a Closet Payload

<button
  id="open-hemsy"
  data-hemsy-trigger="closet"
  data-hemsy-closet="YOUR_URLSAFE_BASE64_CLOSET_PAYLOAD"
>
  Try Look On
</button>

​
Closet Payload

FieldRequiredTypeNotes
productstrueArray<object>Must contain at least 1 product.
products[].variantIdfalsenumber | stringPreferred identifier (most reliable).
products[].productIdfalsenumber | stringOptional fallback identifier when variantId is unavailable.
products[].attributesfalseArray<{ key: string; value: string }>Optional line-item attributes passed through to checkout/cart create.
Each product must include at least one identifier: variantId or productId.

​
Minimal Example

{
  "products": [
    {
      "variantId": 1234567890,
      "attributes": [{ "key": "_bundleTitle", "value": "Starter Bundle" }]
    }
  ]
}

​
Resolution Rules

  • Best: provide variantId for each line item.
  • If variantId is missing, Hemsy can use productId or handle.
  • attributes are preserved and passed to checkout line items.

​
URL-Safe Base64 Encoding

Hemsy expects URL-safe base64:
  • Replace + with -
  • Replace / with _
  • Remove trailing =
function toUrlSafeBase64(obj) {
  return btoa(JSON.stringify(obj))
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");
}

​
End-to-End Example

<button
  id="open-hemsy"
  data-hemsy-trigger="closet"
  data-hemsy-closet="eyJwcm9kdWN0cyI6W3sidmFyaWFudElkIjoxMjM0NTY3ODkwLCJhdHRyaWJ1dGVzIjpbeyJrZXkiOiJfYnVuZGxlVGl0bGUiLCJ2YWx1ZSI6Ik15IEJ1bmRsZSJ9XX1dfQ"
>
  Try it on
</button>
<script
  src="https://hemsy.ai/hemsy-embed.js"
  data-hemsy-subdomain="your-store-subdomain"
  data-hemsy-closet-selector="#open-hemsy"
  data-hemsy-auto-product-context="false"
  defer
></script>