Skip to main content

Embed a perks page

Show your customers a branded perks page on your own site by pasting in a few lines of HTML — no build step, no API calls from your code.

The embed is the fastest way to put Paylode perks in front of your customers. You add a small loader script and a container element to any page — a dashboard, a rewards tab, an order-confirmation screen — and Paylode renders your perks page inside it, themed to your program. If you can edit your site's HTML, you can ship this today. A full custom integration is only worth it when you need to compose the perks experience yourself.

How it works​

The loader script resolves your perks page by its slug — a short identifier for your program — then injects an iframe pointing at your hosted perks page. The widget listens for its own content-height changes and grows the iframe to match, so there's no inner scrollbar.

The perks shown are resolved server-side from your collection. That means when you add, remove, or re-rank perks in the Paylode app, the change appears on your embedded page on the next load — you don't redeploy anything.

Before you begin​

  • Your perks page slug. Find it in the Paylode app under your program's integration settings. Example: example-rewards.
  • A page you can edit. Anywhere you can add HTML to the <head> and <body>.

Steps​

1. Add the stylesheet​

Put this in your page's <head>:

<link rel="stylesheet" href="https://www.paylode.com/paylodePerkIframe.css" />

2. Add the container​

Place the container where you want the perks page to appear. Its data-* attributes configure the widget — data-slug is required, the rest are optional.

<div
  id="paylode-iframe-container"
  data-slug="example-rewards"
  data-lang="en"
  data-utm_source="dashboard"
></div>
AttributeRequired?Effect
data-slugRequiredWhich perks page to render. Case-sensitive.
data-langOptionalLanguage override (e.g. en, fr).
data-categoryOptionalOpen with a category already applied, by slug (e.g. health-wellness).
data-utm_*OptionalForwarded as utm_* context for reporting.
data-cmeta_*OptionalYour own metadata, forwarded as cmeta_*.

For the full attribution story — carrying host-page UTMs and your own ids through to your reports — see cmeta for perk pages. To land customers on one category — including pointing several campaigns at this one page — see Preselect a category.

3. Add the loader script​

Put this near the end of your <body>, after the container exists in the DOM:

<script src="https://www.paylode.com/paylodePerkIframe.js"></script>

That's the whole install. On load, the widget resolves your slug, renders your perks page, and auto-sizes.

Once you're live​

The perks page appears inside your container, themed to your program. The widget mounts the iframe inside your container <div> on load, so to move it, move that <div> — the perks page is a child of it and travels with it. To change which perks show or how they're ordered, edit your collection in the Paylode app; the embed reflects it on the next load.

To review changes yourself without counting as customer views, open your page's hosted address with ?preview-mode=true — see the hosted-page preview note. The embed renders the same surface, so what you preview there is what the embed shows.

Troubleshooting​

caution

The container must be present in the DOM when the loader runs. If the script tag comes before the container, or the container is rendered later by client-side code, the widget can't mount. Add the script after the container, or re-run the loader once the container exists.

note

If your site sends a strict Content-Security-Policy, its frame-src (and style-src/script-src for the loader assets) must allow the Paylode domains, or the frame won't load or resize. The widget sizes itself from height messages it posts, so blocking its origin leaves the frame stuck at its initial height.

Worked example: a rewards tab​

A single page with the perks page embedded in a "Rewards" section:

<!doctype html>
<html>
  <head>
    <title>My account</title>
    <link rel="stylesheet" href="https://www.paylode.com/paylodePerkIframe.css" />
  </head>
  <body>
    <h1>Rewards</h1>
    <div id="paylode-iframe-container" data-slug="example-rewards" data-lang="en"></div>
    <script src="https://www.paylode.com/paylodePerkIframe.js"></script>
  </body>
</html>

On a confirmation page​

The same embed shines right after a purchase — the moment the customer is most engaged. Three placement rules make it work:

  1. Put the perks below the order summary, not above it — the customer's first job is to confirm what they bought. A short heading ("A little something for you") sets the expectation.

  2. Forward the order context so your reports can tie perk activity back to this moment — data-utm_* for campaign-style tags, data-cmeta_* for your own ids (an anonymized order reference, never anything sensitive):

    <div
      id="paylode-iframe-container"
      data-slug="example-rewards"
      data-utm_source="checkout"
      data-utm_medium="confirmation"
      data-cmeta_order_ref="ord_1f2e3d"
    ></div>

    These values travel onto the outbound redemption links and come back in your reports, so post-purchase perks measure separately from your standing rewards tab. Full rules in cmeta for perk pages.

  3. Make sure the container is server-rendered. Confirmation pages are often produced by a commerce platform's templating engine; if the container is injected after the initial HTML, the loader may run before it exists.

Under the hood​

The widget reads your collection through the getPerkCollection operation. You never call it directly for the embed, but if you later want to render perks yourself, that's the same data the custom perk page guide builds on. See the perk-collection operations in the API Reference.