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

> Put the Shoppex checkout inside your own page. What Elements is, how it differs from the Buy Button and Headless, and which one to use.

Elements puts the Shoppex checkout **inside your page**, as a block in your own layout. There is no window over the page and no new tab. The buyer enters their email, picks a payment method and pays without leaving the section they are reading.

```html theme={"system"}
<div
  data-shoppex-element="checkout"
  data-shoppex-shop-id="YOUR_SHOP"
  data-shoppex-product-id="YOUR_PRODUCT_ID"
></div>
<script src="https://checkout.shoppex.io/embed/embed.iife.js" defer></script>
```

The block is an iframe from `checkout.shoppex.io`. It runs the same checkout as the Buy Button and the hosted checkout page: the same payment methods, prices, coupons, fraud checks and Style Center design. Elements works on every plan.

## Elements, Buy Button or Headless

Shoppex has three ways to sell from your own website. All three use the same orders, invoices and webhooks.

| | Buy Button | **Elements** | Headless |
| - | - | - | - |
| Where the buyer pays | In a window over your page | In a block inside your page | In your own checkout UI |
| What you add | The script and a button | The script and a `<div>` | Your own frontend with the SDK |
| Payment fields run on | `checkout.shoppex.io` | `checkout.shoppex.io` | Your page |
| Which sites can use it | Any site | Only your [allowed sites](/developers/elements/sites) | Only your allowed origins |
| Design | Style Center | Style Center plus [appearance](/developers/elements/appearance) per page | Your own UI |
| Plan | Every plan | Every plan | Business |
| Docs | [Checkout Embed SDK](/developers/embeds/overview) | This section | [Headless checkout](/developers/headless/checkout) |

## Which one do I use?

* **Use the Buy Button** when you want the least work. A button on any page opens the checkout in a window. You do not list your sites, and one script serves every button.
* **Use Elements** when the checkout should be part of the page: a pricing section, a landing page, a product page where the buyer stays in context. You write no checkout code. You list the sites that may show it.
* **Use Headless** when you want to build the checkout UI yourself: your own fields, your own steps, your own components. Shoppex still runs the payment and the delivery.

You can mix them. The Buy Button and Elements use the same script, so a page can have buy buttons for some products and one Elements block for the main product.

## What the block does

* **Steps.** Email, then payment, then success. The block shows the order summary, the payment methods the shop has turned on, and "Powered by Shoppex".
* **Height.** The block fills the width of its container and grows with its content. Your page does not need a fixed height.
* **Allowed sites.** The block loads only on the sites you list in the dashboard. The browser enforces this. See [Allowed sites](/developers/elements/sites).
* **Appearance.** Each page can set a few design values, like dark mode, an accent colour or the corner radius. See [Appearance](/developers/elements/appearance).
* **Events.** Your page hears `ready`, `step`, `success`, `error` and more, with stable error codes. See [Events and error codes](/developers/elements/events).
* **Test mode.** The full flow with the real products and prices, and nobody pays. See [Test mode](/developers/elements/test-mode).

## Payment methods in the block

Card payments, Link, Google Pay, crypto, manual methods and balance stay inside the block. Some methods hand the buyer to the provider: PayPal opens its own window, and redirect gateways open the hosted invoice in a new tab while the block waits for the payment. The block tells your page before it does this, with the `redirect` event.

> [!NOTE]
>
> Apple Pay in an iframe needs your site's domain registered with Stripe. Add it in Stripe under **Settings → Payment method domains**. Shoppex registers `checkout.shoppex.io`, `embed.shoppex.io` and your verified custom domains for you.

## Deliver orders from webhooks

The `success` event tells your page that the buyer finished. It is not proof of payment, because any script on the page can fake a browser event. Deliver orders from [webhooks](/developers/webhooks) or the [Developer API](/developers/invoices), as you do for every other Shoppex checkout.

## Limits in this version

* One block per page. A second `Shoppex.mount` reports `already_mounted`.
* One product per block, a product group, or an invoice your server created.
* The block shows "Powered by Shoppex".
* Your page cannot start or confirm a payment, or change the amount or the items. Only the buyer can, inside the block.

## Next steps

> **[Quick start](/developers/elements/quickstart)**
>
> Add your first block and test it in a few minutes.

> **[Mount and options](/developers/elements/reference)**
>
> `Shoppex.mount`, the HTML block, React and every option.

> **[Security and CSP](/developers/elements/security)**
>
> What your Content Security Policy needs, and what the block protects.

> **[Events and error codes](/developers/elements/events)**
>
> Every event your page can hear, and every error code.


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