> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```html theme={"system"}
<script src="https://checkout.shoppex.io/embed/embed.iife.js" defer></script>
```

### Option A: Data attributes (fastest)

```html theme={"system"}
<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="customer@example.com"
  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

```html theme={"system"}
<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)

```html theme={"system"}
<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

```javascript theme={"system"}
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.

```tsx theme={"system"}
<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

<CardGroup cols={2}>
  <Card title="Copy/Paste Snippets" icon="code" href="/guides/embeds-snippets">
    Ready-to-use snippets for Next.js, React, WordPress, and Webflow.
  </Card>

  <Card title="Embed SDK Reference" icon="book" href="/guides/embeds-reference">
    Full config, data attributes, API methods, and event contracts.
  </Card>

  <Card title="Security & Troubleshooting" icon="shield" href="/guides/embeds-security">
    CSP, origin rules, and production debugging checklist.
  </Card>

  <Card title="Headless Checkout SDK" icon="credit-card" href="/headless/checkout">
    Build your own checkout UI when modal checkout is not enough.
  </Card>

  <Card title="Embed Demo" icon="laptop-binary" href="https://checkout.shoppex.io/embed/demo.html">
    Interactive demo with real embed patterns.
  </Card>

  <Card title="Storefront SDK" icon="browser" href="/sdk/introduction">
    Build full storefront UI when modal-only checkout is not enough.
  </Card>
</CardGroup>