Elements quick start

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.

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 for every rule.

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.

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.

index.html

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

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 to simulate errors.

Go live

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

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

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 or the Developer API. 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.

Start here

Agents & CLI

Products

Invoices and payments

Webhooks

Headless commerce

Storefront SDK

Checkout embeds

Elements

Integrations

Resellers

Email marketing

Tutorials

Elements quick start

The block does not load

​The block does not load

The block does not load