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

​
1) Declarative (data attributes)

The SDK auto-binds clickable elements matching:
  • [data-shoppex-product-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>

​
2) Programmatic (JavaScript API)

Shoppex.open({
  items: [
    { productId: 'PRODUCT_ID', variantId: 'VARIANT_ID', quantity: 1 }
  ],
  theme: 'auto',
  email: '[email protected]',
  couponCode: 'SAVE20',
  returnUrl: 'https://your-site.com/thank-you',
  metadata: { campaign: 'launch' }
});

​
Data Attributes

AttributeRequiredDescription
data-shoppex-product-idYes*Product 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-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. 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;
  items: Array<{
    productId: string;
    variantId?: string;
    quantity?: number;
  }>;
  theme?: 'light' | 'dark' | 'auto';
  returnUrl?: string;
  email?: string;
  couponCode?: string;
  metadata?: Record<string, string>;
};
Important behavior:
  • items must contain at least one valid productId.
  • 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
Supported query params sent by SDK:
  • quantity
  • variantId
  • theme (only when not auto)
  • returnUrl
  • email
  • couponCode
  • 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.