Checkout Embed SDK

Add Shoppex checkout as a modal on your existing website

The Checkout Embed SDK lets you open Shoppex checkout in a modal, directly on your site.

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 + 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="[e-mail]"
  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 are supported through data-shoppex-group-id or Shoppex.open({ groupId }).
• Group embeds show a product picker first, then continue into the normal product checkout.
• Multiple items are accepted by the API, but 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 is the setup that caused 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 developer language:

• window.Shoppex handles the modal checkout.
• Your app still needs product data from somewhere if you want to build custom cards around it.

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 just app-level code you may 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.

---

Next Steps

Copy/Paste Snippets

Ready-to-use snippets for Next.js, React, WordPress, and Webflow.

Embed SDK Reference

Full config, data attributes, API methods, and event contracts.

Security & Troubleshooting

CSP, origin rules, and production debugging checklist.

Headless Checkout SDK

Build your own checkout UI when modal checkout is not enough.

Embed Demo

Interactive demo with real embed patterns.

Storefront SDK

Build full storefront UI when modal-only checkout is not enough.