Skip to main content
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 caseBest choice
Open checkout in a modal from any pageCheckout Embed SDK (window.Shoppex)
Build a full storefront UI (products/cart/state)Storefront SDK (@shoppexio/storefront)

​
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 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 buildingWhat you need
One buy button on an existing pageEmbed SDK only
Custom landing page with your own product cardsEmbed SDK + product data source
Full storefront with cart/state/searchStorefront 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.

Embed Demo

Interactive demo with real embed patterns.

Storefront SDK

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