Build Live Entry Displays

From admin settings to your display #

Use our API documentation to connect your displays to Clean Sweeps. Your storefront requests the current entry rules and turns them into a badge, card, or other custom display. You control the layout, colors, and typography.

1. Identify the shop and product. Supply their Shopify GIDs and your intended sweepstake ID.
2. Retrieve the rules. Use Product Entry Display API to fetch eligibility, base rules, product overrides, and scheduled bonus settings.
3. Read the current variant price. Pass a numeric price in dollars for the documented dollar-based calculation. Do not parse formatted currency text.
4. Calculate the display. Apply subtotal rounding, scheduled entry-rate overrides, product multipliers, and bonus entries in the documented order.
5. Update the badge. Replace its text and accessible description. Recalculate when the selected variant price changes.

Start with a display you like #

The preview above uses hardcoded sample values. Add the HTML where the badge belongs and scope the CSS to this component. Both values can be replaced without changing its appearance.

<div id="product-entries" class="cs-entry-badge" role="img"
     aria-label="9,000 entries, 300X multiplier">
  <span class="cs-entry-badge__entries" aria-hidden="true">
    <span data-entry-value>9,000</span>
    <small data-entry-unit>Entries</small>
  </span>
  <span class="cs-entry-badge__multiplier" data-entry-multiplier aria-hidden="true">300X</span>
</div>

For illustration only: $30 × 100 entries per $1 × a 3× product multiplier = 9,000 entries. The displayed effective entry multiplier is 300X. These are sample rules, not values from a live store.

Replace sample values with API data #

Download entry-display.mjs or copy the API JavaScript tab into a module of that name. Add it to your storefront assets and initialize it after the badge’s HTML exists. Adjust the import URL for your theme’s asset hosting.

import { connectEntryDisplays } from './entry-display.mjs';

const badge = document.getElementById('product-entries');
const display = connectEntryDisplays({
  shopId: 'gid://shopify/Shop/YOUR_SHOP_ID',
  sweepstakeId: 123,
  displays: [{
    element: badge,
    productId: 'gid://shopify/Product/YOUR_PRODUCT_ID',
    price: 30
  }],
  refreshMs: 60000
});

// Call from your theme's actual variant-change handler:
// display.updatePrice(badge, selectedVariant.price / 100);

// Call when the product section is removed or reinitialized:
// display.destroy();

Replace the placeholder shop and product IDs, sweepstake ID, and price. In Shopify Liquid, {{ shop.id }} and {{ product.id }} provide numeric IDs for your GIDs. Use your selected variant’s price, not a fixed example value. Shopify variant prices are in currency subunits; the example division by 100 applies to the documented dollar-based price.

Use the theme’s actual variant-change handler to call updatePrice. Shopify themes differ; there is no theme event assumed by this example. See Shopify’s variant guidance.

For multiple badges, pass every badge in the same displays array. The helper batches product IDs in one request and shares the refresh loop. Call destroy() before recreating a controller when a theme section is replaced.

Keep admin changes visible #

Your display asks Clean Sweeps for the latest settings when the page opens, every 60 seconds while the page is visible, and when a visitor returns to the tab. After you change a multiplier or entry rule in the admin app, the display updates when its next check succeeds. There can be a short delay before customers see your change, and a failed connection can make it take longer.

• Fetch rules when the display starts.
• Recalculate immediately from cached rules when a variant price changes.
• Refresh rules every 60 seconds while visible, and when the page becomes visible again.
• Pause background polling, batch product IDs, and prevent overlapping requests.
• Time out stalled requests after 10 seconds and back off after failures, up to eight times the configured interval.

You can change how often this example checks for updates. The 60-second setting is a starting point, not a promise that every change will appear within a minute. For stores with many visitors or product displays, contact the Clean Sweeps team for guidance.

Make the display dependable #

• Not eligible: hide the multiplier when the product or default rule excludes entries.
• Entries unavailable: hide the multiplier on HTTP/GraphQL failure, missing rules, malformed JSON, or invalid calculation inputs.
• Small multipliers: hide the multiplier when its value is 1 or less.
• Obsolete responses: ignore results after teardown or after a newer visibility session starts.

The helper follows the documented sweepstake selection order: matching ID, then first active sweepstake, then first result. If your display must never fall back to another sweepstake, adapt that selection explicitly.