Skip to main content

Redemption Integration Guide

Learn how to accept Loyalteez perks on your website.

Overview​

The Loyalteez "Stealth Redemption" system allows you to accept rewards (like discount codes) without complex backend integrations. The entire process happens securely in the customer's browser.

How it Works​

  1. Detection: When a customer visits your site (and enters their email or is logged in), our SDK checks if they have any unused perks.
  2. Notification: If a perk is found, a "Reward Available" toast appears.
  3. Redemption: The customer clicks "Apply". We verify their ownership and consume the perk.
  4. Execution: Our SDK hands the "Redemption Data" (e.g., your coupon code) to your website via a JavaScript event.

Integration Steps​

1. Configure Your Perk​

When creating or editing a Perk in the Partner Dashboard:

  1. Scroll to Redemption Configuration.
  2. Select Type: Code (most common).
  3. Enter the Value (e.g., VIP-SUMMER-2025).
    • Note: This code is encrypted and hidden from the user until they successfully redeem the perk.

2. Install the SDK​

Ensure the Loyalteez SDK is installed on your website (usually in the <head> or Footer).

<script src="https://reward.loyalteez.app/sdk.js"></script>
<script>
  LoyalteezAutomation.init('YOUR_BRAND_ID');
</script>

3. Handle the Event (The "Glue")​

Copy and paste this snippet into your website's code (e.g., "Custom Code" or "Footer Code" section). This script listens for the redemption and applies the discount.

Best Practice: Place this on your Cart / Basket Page to ensure compatibility.

document.addEventListener('loyalteez:perk-redeemed', (e) => {
  const { result } = e.detail;
  const { redemption_data } = result;

  if (result.success && redemption_data?.type === 'code') {
    // 1. Find the coupon input field (Inspect Element to find the ID)
    const input = document.querySelector('#coupon_code'); // REPLACE '#coupon_code' with your actual input ID
    
    // 2. Paste the code
    if (input) {
       input.value = redemption_data.value;
       
       // 3. Click the Apply button
       const applyBtn = document.querySelector('#apply_btn'); // REPLACE '#apply_btn' with your button ID
       if (applyBtn) applyBtn.click();
    } else {
       // Fallback: Show the code to the user
       alert('Your code is: ' + redemption_data.value);
    }
  }
});

Need to Know (Important)​

🛒 Cart vs. Checkout​

Recommendation: Always integrate on the Cart / Basket Page. Many platforms (like Shopify Basic) lock the Checkout page, meaning custom scripts cannot run there. By handling the discount in the Cart (before they click "Checkout"), the discount is usually passed through automatically.

🖼️ Iframes and Widgets (Booking Tools)​

If your checkout uses an embedded widget (Iframe), our script cannot automatically fill fields inside it due to browser security rules.

The Solution: "Widget Mode"

  1. In your Perk Settings, enable "Enable Widget / Iframe Mode".
  2. This updates the SDK behavior: When a user redeems, we automatically add ?coupon=YOUR_CODE to the URL.
  3. Many booking widgets (like Calendly, FareHarbor, etc.) automatically read this URL parameter and apply the discount.

Check your widget provider's documentation to confirm they support URL-based coupons.

🔒 Prevent Code Sharing (Unique Codes)​

If you are worried about users sharing a static code (e.g., VIP2025), you can enable "Single-use Code" in the Perk Settings.

  • How it works: We append a unique suffix to your base code (e.g., VIP2025-ABCD).
  • Requirement: Your e-commerce store must be configured to accept these unique codes. Typically, you would pre-generate a batch of coupons (e.g., VIP2025-0001 to VIP2025-9999) and upload them to your store.

📚 Platform Guides: Setting up Bulk Codes​

When you enable Single-use Code mode, Loyalteez appends a unique identifier to your base code (e.g., VIP2025 becomes VIP2025-7A3F). This prevents customers from sharing codes with friends.

The catch: Your e-commerce platform must recognize these unique codes. This means you need to pre-generate a batch of codes in your store that match the pattern.

How Single-use Codes Work​

  1. You enter a base code in Loyalteez (e.g., SUMMER25)
  2. When a customer redeems, we append a unique suffix: SUMMER25-X7K9
  3. Your store must have SUMMER25-X7K9 (and many others) already created as valid coupons

How Many Codes to Generate?​

We recommend generating at least 1,000 unique codes per perk. If you expect high volume, generate more. Most platforms support bulk import via CSV.

Platform-Specific Guides​

Shopify​

Shopify's native discount system doesn't support bulk code generation. Use the free Bulk Discount Code Generator app by Shopify:

  1. Install the app from the Shopify App Store
  2. Go to Discounts → Create a new discount
  3. Select "Amount off order" or "Amount off products"
  4. Under Discount code, click "Generate codes"
  5. Enter your base code pattern (e.g., SUMMER25-)
  6. Set the number of codes to generate (1,000+)
  7. Export the codes and keep them for reference

📖 Official Docs: Managing Discounts

WooCommerce​

Use the Smart Coupons extension or import via CSV:

  1. Install Smart Coupons or a similar bulk coupon plugin
  2. Create a base coupon with your desired discount settings
  3. Use the "Generate Coupons" feature to create unique variants
  4. Alternatively, prepare a CSV with columns: code, discount_type, amount and import

📖 Official Docs: Coupon Management

BigCommerce​

BigCommerce supports bulk code creation via API or third-party apps:

  1. Go to Marketing → Promotions → Coupon Codes
  2. Create a promotion with your discount settings
  3. Use the Bulk Coupon Generator feature or API to generate unique codes
  4. For large batches, use the Coupons API

📖 Official Docs: Using Coupon Codes

Squarespace​

Squarespace has limited native support for bulk unique codes:

  1. Go to Commerce → Discounts
  2. Create individual discount codes manually, or
  3. Use third-party integrations via Zapier to automate code creation
  4. Consider using a different redemption strategy if you need thousands of codes

📖 Official Docs: Creating Discounts

Other Platforms​

For platforms not listed above:

  • Look for "bulk coupon" or "coupon import" features in your admin panel
  • Check if CSV import is supported for discount codes
  • Contact your platform's support for guidance on unique code generation
Code Naming Convention

When generating bulk codes, use a consistent prefix that matches what you entered in Loyalteez. For example, if your base code is VIP25, generate codes like:

  • VIP25-0001
  • VIP25-0002
  • VIP25-ABCD
  • etc.

🕵️ Hidden Fields​

If your coupon field is hidden behind a "Have a promo code?" link, your script must click that link first.

if (!document.querySelector('#coupon_input')) {
   document.querySelector('#show_promo_link').click();
   // ... then fill the input
}