> ## 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.

# Elements quick start

> Add the Shoppex checkout to your page, test it without paying, and go live.

This guide puts one checkout block on your page, runs a test purchase and then switches it to live. You need a Shoppex shop with at least one public product.

You need two values from the dashboard:

* **Your shop ID.** Your shop's slug.
* **Your product ID.** Open **Store → Channels → Embed Hub → Elements** and pick the product under **Add to your site**. The code there already has both values filled in.

**1. Add your site**

Open **Store → Channels → Embed Hub → Elements**. Under **Allowed sites**, enter the address of your site, for example `https://shop.example.com`, click **Add Site**, then **Save Changes**.

Only listed sites can show a live checkout. Enter the exact origin: `https://www.example.com` and `https://example.com` are two different sites. Changes reach your site within a minute. See [Allowed sites](/developers/elements/sites) for every rule.

> [!TIP]
>
> Working on `http://localhost` or `http://127.0.0.1`? Test mode runs there without a list entry, so you can skip this step until you go live.

**2. Place the checkout**

Put the `<div>` where buyers should pay, and the script once before `</body>`. Pages that already have Shoppex buy buttons already have the script.

```html index.html theme={"system"}
<!doctype html>
<html>
  <body>
    <h1>Pro License</h1>

    <div
      data-shoppex-element="checkout"
      data-shoppex-shop-id="YOUR_SHOP"
      data-shoppex-product-id="YOUR_PRODUCT_ID"
      data-shoppex-mode="test"
    ></div>

    <script src="https://checkout.shoppex.io/embed/embed.iife.js" defer></script>
    <script>
      document.addEventListener('shoppex:element:success', (event) => {
        console.log('Order placed', event.detail.invoiceId);
      });
    </script>
  </body>
</html>
```

Replace `YOUR_SHOP` and `YOUR_PRODUCT_ID`. The block fills the width of the `<div>` and grows with its content.

If your site sends a `Content-Security-Policy` header, add the Shoppex sources first. See [Security and CSP](/developers/elements/security#content-security-policy).

**3. Test a purchase**

Open the page. The block shows the product and a **Test mode** badge. Enter an email, pick a payment method and click **Pay … · Test**.

The block shows the success screen, and the browser console prints `Order placed test_…`. Test mode creates no invoice and charges nothing. See [Test mode](/developers/elements/test-mode) to simulate errors.

**4. Go live**

Change `data-shoppex-mode="test"` to `data-shoppex-mode="live"` and publish the page on a site from your list.

```html theme={"system"}
<div
  data-shoppex-element="checkout"
  data-shoppex-shop-id="YOUR_SHOP"
  data-shoppex-product-id="YOUR_PRODUCT_ID"
  data-shoppex-mode="live"
></div>
```

Live is also the default when you leave out `data-shoppex-mode`.

**5. Deliver the order**

Shoppex delivers the product itself, as for every other checkout. If your own system has to act on the order, use the `order:paid` [webhook](/developers/webhook-events) or the [Developer API](/developers/invoices). Do not deliver from the `success` event: it is a browser event, and any script on the page can send one.

## The block does not load

| What you see | Why | What to do |
| - | - | - |
| "This checkout isn't available on this site." | The page's origin is not on your allowed sites. | Add the exact origin under **Allowed sites** and save. The console prints the origin the block saw, and **Blocked recently** in the dashboard lists it with **Allow**. |
| "Checkout didn't load" with **Try again** | Shoppex did not answer, or the frame did not load within 15 seconds. | Click **Try again**. If it repeats, check `connect-src` and `frame-src` in your CSP. |
| "Checkout didn't load" without **Try again** | The block's options are wrong, for example an empty shop ID or an unknown shop. | The console names the option. |
| Nothing at all | The script did not load. | Check the console and `script-src` in your CSP. |

Add `debug: true` to `Shoppex.mount` to log every message between the page and the block. See [Mount and options](/developers/elements/reference).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.