Checkout Embed SDK

The Checkout Embed SDK opens Shoppex checkout in a modal, directly on your site, with a script tag and no build step.

What this is (and what it is not)

Use case	Best choice
Open checkout in a modal from any page	Checkout Embed SDK (`window.Shoppex`) — Standard and Business
Build a full storefront UI (products/cart/state)	Storefront SDK (`@shoppexio/storefront`)
Build your own checkout UI with Shoppex handling payment and fulfillment	Headless Checkout SDK (`@shoppexio/checkout-js/headless`) — Business

Quick start

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

Option A: data attributes (fastest)

<button
  data-shoppex-shop-id="YOUR_SHOP"
  data-shoppex-product-id="PRODUCT_ID"
  data-shoppex-variant-id="VARIANT_ID"
  data-shoppex-quantity="1"
  data-shoppex-email="[email protected]"
  data-shoppex-coupon-code="SAVE20"
  data-shoppex-referral-code="CREATOR123"
  data-shoppex-return-url="https://your-site.com/thank-you"
  data-shoppex-metadata='{"source":"landing","campaign":"spring"}'
>
  Buy now
</button>

Option A2: 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>

Option B: JavaScript API (more control)

<script>
  Shoppex.open({
    shopId: 'YOUR_SHOP',
    items: [{ productId: 'PRODUCT_ID', variantId: 'VARIANT_ID', quantity: 1 }],
    theme: 'auto',
    returnUrl: 'https://your-site.com/thank-you',
    couponCode: 'SAVE20',
    affiliateCode: 'CREATOR123',
    metadata: {
      source: 'landing',
      campaign: 'spring'
    }
  });
</script>

Common events

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

document.addEventListener('shoppex:error', (event) => {
  console.error('Checkout error:', event.detail.error);
});

Current behavior to know

Group embeds work through data-shoppex-group-id or Shoppex.open({ groupId }).
Group embeds show a product picker first, then continue into the normal product checkout.
The API accepts multiple items, but the current modal flow uses the first valid item.
Quantity is normalized to 1..999.
Invalid or empty items do not open checkout, unless a valid groupId is provided.

If you already have your own product cards

This setup causes the most confusion in real projects, so here is the simple rule.

Use the Checkout Embed SDK when you only need Shoppex to open checkout.
Use a product data source when you also render your own product list, prices, images, stock, or categories.

In plain terms:

window.Shoppex handles the modal checkout.
If you want to build custom cards around it, your app still needs product data from somewhere.

Common setups:

What you are building	What you need
One buy button on an existing page	Embed SDK only
Custom landing page with your own product cards	Embed SDK + product data source
Full storefront with cart/state/search	Storefront SDK (`@shoppexio/storefront`)

Typical product data sources:

Shoppex Storefront API
Storefront SDK (@shoppexio/storefront)
Your own backend that already proxies Shoppex product data

Important:

data-shoppex-product-id is part of the public Embed SDK integration.
data-shoppex-group-id is also part of the public Embed SDK integration.
Local helpers, TypeScript types, or lib/shoppex.ts-style files are not required by Shoppex itself.
Those files are app-level code you can add to keep your own project organized.

<ProductCard
  title={product.title}
  price={product.price}
  image={product.image}
>
  <button data-shoppex-product-id={product.id}>
    Buy now
  </button>
</ProductCard>

Here, your app owns the ProductCard, and Shoppex owns the checkout modal.

Framework snippets

Replace all placeholder values: PRODUCT_ID, GROUP_ID, VARIANT_ID, and https://your-site.com/thank-you.

Next.js

'use client';

import Script from 'next/script';

declare global {
  interface Window {
    Shoppex?: {
      open: (options: {
        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>;
      }) => void;
    };
  }
}

export default function BuyButton() {
  const openCheckout = () => {
    window.Shoppex?.open({
      shopId: 'YOUR_SHOP',
      items: [{ productId: 'PRODUCT_ID', variantId: 'VARIANT_ID', quantity: 1 }],
      theme: 'auto',
      returnUrl: 'https://your-site.com/thank-you',
      affiliateCode: 'CREATOR123',
      metadata: { source: 'landing' },
    });
  };

  return (
    <>
      <Script
        src="https://checkout.shoppex.io/embed/embed.iife.js"
        strategy="afterInteractive"
      />
      <button onClick={openCheckout}>Buy now</button>
    </>
  );
}

React SPA

import { useEffect } from 'react';

declare global {
  interface Window {
    Shoppex?: {
      open: (options: {
        groupId?: string;
        items: Array<{ productId: string; variantId?: string; quantity?: number }>;
        theme?: 'light' | 'dark' | 'auto';
        affiliateCode?: string;
      }) => void;
    };
  }
}

export function BuyButton() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://checkout.shoppex.io/embed/embed.iife.js';
    script.defer = true;
    document.body.appendChild(script);

    return () => {
      document.body.removeChild(script);
    };
  }, []);

  return (
    <button
      onClick={() =>
        window.Shoppex?.open({
          items: [{ productId: 'PRODUCT_ID', variantId: 'VARIANT_ID', quantity: 1 }],
          theme: 'auto',
          affiliateCode: 'CREATOR123',
        })
      }
    >
      Buy now
    </button>
  );
}

WordPress

Paste this into a Custom HTML block.

<button
  data-shoppex-product-id="PRODUCT_ID"
  data-shoppex-variant-id="VARIANT_ID"
  data-shoppex-quantity="1"
  data-shoppex-theme="auto"
  data-shoppex-referral-code="CREATOR123"
  data-shoppex-return-url="https://your-site.com/thank-you"
>
  Buy now
</button>

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

If your theme strips script tags, add the script globally, for example in footer settings or the theme template, and keep only the button markup in content.

Webflow

Add an Embed element and paste this.

<button
  data-shoppex-product-id="PRODUCT_ID"
  data-shoppex-variant-id="VARIANT_ID"
  data-shoppex-quantity="1"
  data-shoppex-email="[email protected]"
  data-shoppex-coupon-code="SAVE20"
  data-shoppex-metadata='{"source":"webflow"}'
>
  Buy now
</button>

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

If you already load the script site-wide in Webflow project settings, keep only the button in each Embed block.

Bonus: programmatic multi-item button

<button id="open-checkout">Checkout bundle</button>
<script src="https://checkout.shoppex.io/embed/embed.iife.js" defer></script>
<script>
  document.getElementById('open-checkout').addEventListener('click', () => {
    Shoppex.open({
      items: [
        { productId: 'PRODUCT_ID_1', variantId: 'VARIANT_1', quantity: 1 },
        { productId: 'PRODUCT_ID_2', quantity: 2 }
      ],
      theme: 'auto',
      couponCode: 'SAVE20'
    });
  });
</script>

The current modal flow uses the first valid item when multiple items are passed.

Group embed button

<button
  data-shoppex-group-id="GROUP_ID"
  data-shoppex-theme="auto"
  data-shoppex-referral-code="CREATOR123"
  data-shoppex-return-url="https://your-site.com/thank-you"
>
  Open group
</button>

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

Use this when you want buyers to choose one product from a Shoppex group inside the modal. The group view opens first, and when the buyer picks a product, Shoppex continues into the normal product checkout flow.

Hybrid: your own product cards + Shoppex checkout

Use this when you already render your own catalog UI and only want Shoppex for the checkout modal. Fetch product data however you want, render your own cards, and put data-shoppex-product-id on the CTA button. Shoppex handles the rest.

'use client';

import Script from 'next/script';

type Product = {
  id: string;
  title: string;
  price: string;
  imageUrl?: string;
};

export function ProductGrid({ products }: { products: Product[] }) {
  return (
    <>
      <Script
        src="https://checkout.shoppex.io/embed/embed.iife.js"
        strategy="afterInteractive"
      />

      <div className="grid gap-4 md:grid-cols-3">
        {products.map((product) => (
          <article key={product.id} className="rounded-xl border p-4">
            {product.imageUrl ? (
              <img src={product.imageUrl} alt={product.title} />
            ) : null}

            <h3>{product.title}</h3>
            <p>{product.price}</p>

            <button
              data-shoppex-product-id={product.id}
              data-shoppex-quantity="1"
              data-shoppex-theme="auto"
            >
              Buy now
            </button>
          </article>
        ))}
      </div>
    </>
  );
}

Notes:

The product card layout is yours, not Shoppex’s.
The checkout modal is Shoppex’s.
You can get products from the Storefront API, @shoppexio/storefront, or your own backend.
You do not need to copy any specific lib/shoppex.ts file from another project. That kind of helper is one possible app structure.

Event snippet (analytics)

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

  document.addEventListener('shoppex:error', (event) => {
    console.error('Checkout error:', event.detail.error);
  });
</script>

Embed SDK reference

Full config, data attributes, API methods, event contracts, CSP, and the production checklist.

Embed demo

Interactive demo with real embed patterns.

Start here

Invoices and payments

Webhooks

Headless commerce

Storefront SDK

Checkout embeds

Integrations

Resellers

Email marketing

Tutorials

Checkout Embed SDK

What this is (and what it is not)

Quick start

Common events

Current behavior to know

If you already have your own product cards

Framework snippets

Next.js

React SPA

WordPress

Webflow

Bonus: programmatic multi-item button

Group embed button

Hybrid: your own product cards + Shoppex checkout

Event snippet (analytics)

Embed SDK reference

Embed demo

​What this is (and what it is not)

​Quick start

​Common events

​Current behavior to know

​If you already have your own product cards

​Framework snippets

​Next.js

​React SPA

​WordPress

​Webflow

​Bonus: programmatic multi-item button

​Group embed button

​Hybrid: your own product cards + Shoppex checkout

​Event snippet (analytics)

Embed SDK reference

Embed demo

What this is (and what it is not)

Quick start

Common events

Current behavior to know

If you already have your own product cards

Framework snippets

Next.js

React SPA

WordPress

Webflow

Bonus: programmatic multi-item button

Group embed button

Hybrid: your own product cards + Shoppex checkout

Event snippet (analytics)