Skip to main content
This page documents the current behavior of the Checkout Embed SDK (window.Shoppex).

​
Script

<script src="https://checkout.shoppex.io/embed/embed.iife.js" defer></script>
Global object: 
window.Shoppex

​
Integration Modes

The SDK auto-binds clickable elements matching:
  • [data-shoppex-product-id]
  • [data-shoppex-group-id]
  • [data-shoppex-checkout]
Simple button:
<button
  data-shoppex-product-id="PRODUCT_ID"
  data-shoppex-variant-id="VARIANT_ID"
  data-shoppex-quantity="1"
  data-shoppex-theme="auto"
>
  Buy now
</button>
Multi-item via JSON:
<button
  data-shoppex-checkout="1"
  data-shoppex-items='[
    {"productId":"PRODUCT_ID_1","variantId":"VARIANT_1","quantity":1},
    {"productId":"PRODUCT_ID_2","quantity":2}
  ]'
>
  Checkout
</button>
Group button:
<button
  data-shoppex-group-id="GROUP_ID"
  data-shoppex-referral-code="CREATOR123"
  data-shoppex-return-url="https://your-site.com/thank-you"
>
  Open group
</button>

​
Data Attributes

AttributeRequiredDescription
data-shoppex-product-idYes*Product identifier
data-shoppex-group-idYes**Group identifier
data-shoppex-variant-idNoVariant identifier
data-shoppex-quantityNoQuantity (1..999, default 1)
data-shoppex-themeNolight, dark, auto (default auto)
data-shoppex-return-urlNoReturn URL after checkout
data-shoppex-emailNoPrefill customer email
data-shoppex-coupon-codeNoPrefill coupon code
data-shoppex-affiliate-codeNoAffiliate code
data-shoppex-referral-codeNoReferral code alias
data-shoppex-metadataNoJSON object with string values
data-shoppex-itemsNoJSON array of checkout items
data-shoppex-shop-idNoOptional field in current API payload
data-shoppex-checkoutNoMarker selector for custom triggers
* Required unless data-shoppex-items contains at least one valid item. ** Required when you want to open a group instead of a product checkout. data-shoppex-metadata example: 
<button
  data-shoppex-product-id="PRODUCT_ID"
  data-shoppex-metadata='{"campaign":"summer","source":"landing"}'
>
  Buy now
</button>

​
JavaScript API

​
Shoppex.init(config?)

Initializes bindings and keyboard handlers. 
Shoppex.init({
  nonce: 'YOUR_CSP_NONCE'
});
Notes:
  • Usually optional because the script initializes automatically.
  • Safe to call multiple times; first call wins.

​
Shoppex.open(options)

Opens modal checkout. 
type CheckoutOptions = {
  shopId?: string;
  groupId?: string;
  items: Array<{
    productId: string;
    variantId?: string;
    quantity?: number;
  }>;
  theme?: 'light' | 'dark' | 'auto';
  returnUrl?: string;
  email?: string;
  couponCode?: string;
  affiliateCode?: string;
  metadata?: Record<string, string>;
};
Important behavior:
  • items must contain at least one valid productId, unless groupId is provided.
  • groupId opens a group picker first, then forwards the buyer into the normal product checkout page.
  • If more than one item is passed, current modal flow uses the first valid item.
  • Calling open() while a modal is open closes the old modal first.

​
Shoppex.close()

Closes the modal programmatically. 
Shoppex.close();

​
Events

Listen on document: 
document.addEventListener('shoppex:success', (event) => {
  console.log(event.detail.invoiceId);
});

document.addEventListener('shoppex:error', (event) => {
  console.error(event.detail.error);
});
Event payloads:
EventDetail
shoppex:success{ invoiceId?: string }
shoppex:error{ error?: string }
Internal iframe events used by the SDK:
  • shoppex:ready
  • shoppex:resize
  • shoppex:close

​
URL Mapping

The SDK resolves checkout iframe URLs to: 
https://checkout.shoppex.io/e/:productId
https://checkout.shoppex.io/g/:groupId
Supported query params sent by SDK:
  • quantity
  • variantId
  • theme (only when not auto)
  • flow
  • shopId
  • returnUrl
  • email
  • couponCode
  • affiliateCode
  • metadata[key]=value

​
Runtime Behavior

  • Modal uses Shadow DOM (mode: closed) for style isolation.
  • Escape, backdrop click, and close button all close modal.
  • Dynamically inserted buttons are auto-bound (MutationObserver).
  • Message handling only accepts trusted checkout origins.

​
Practical Example

<button id="buy">Buy now</button>
<script src="https://checkout.shoppex.io/embed/embed.iife.js" defer></script>
<script>
  document.getElementById('buy').addEventListener('click', () => {
    Shoppex.open({
      items: [{ productId: 'PRODUCT_ID', quantity: 1 }],
      theme: 'auto'
    });
  });

  document.addEventListener('shoppex:success', (event) => {
    console.log('Invoice paid:', event.detail.invoiceId);
  });
</script>

​
Need Faster Setup?

Copy/Paste Snippets

Framework snippets for Next.js, React, WordPress, and Webflow.