# Giveaway Gator - Master Help Document > Compiled from Notion documentation. Intended for the help center chatbot knowledge base. --- ## Table of Contents 1. [What Is Giveaway Gator?](#1-what-is-giveaway-gator) 2. [How Entry Math Works](#2-how-entry-math-works) 3. [Getting Started / Initial Setup](#3-getting-started--initial-setup) 4. [Bonus Periods (Product Bonus Periods)](#4-bonus-periods-product-bonus-periods) 5. [Order Bonuses](#5-order-bonuses) 6. [Order Bonus Progress Bar](#6-order-bonus-progress-bar) 7. [Countdown Timer](#7-countdown-timer) 8. [Countdown Progress Bar](#8-countdown-progress-bar) 9. [Bonus Discount Codes](#9-bonus-discount-codes) 10. [Order Multiplier Products](#10-order-multiplier-products) 11. [Displaying Entries on Product Cards](#11-displaying-entries-on-product-cards) 12. [How Customers See Their Entries](#12-how-customers-see-their-entries) 13. [Exporting Entries](#13-exporting-entries) 14. [Manual Entries](#14-manual-entries) 15. [Thank You Page Entries Display](#15-thank-you-page-entries-display) 16. [Test Mode - Preview Before Going Live](#16-test-mode--preview-before-going-live) 17. [Product Bonuses Admin Block (Shopify Admin)](#17-product-bonuses-admin-block-shopify-admin) 18. [Order Entries Admin Extensions (Shopify Admin)](#18-order-entries-admin-extensions-shopify-admin) 19. [Manual Entries API](#19-manual-entries-api) 20. [POS Claim External API](#20-pos-claim-external-api) 21. [FAQs](#21-faqs) 22. [Post-Purchase Surveys (Unlimited Pro)](#22-post-purchase-surveys-unlimited-pro) 23. [Post-Purchase Actions (Unlimited Pro)](#23-post-purchase-actions-unlimited-pro) 24. [Plans & Pricing](#24-plans--pricing) --- ## 1. What Is Giveaway Gator? Giveaway Gator is a Shopify app that lets you run automated sweepstakes and giveaway promotions. Instead of discounting your products, you reward customers with giveaway entries for every purchase they make — driving sales, increasing average order value, and building excitement around your brand. ### The Problem It Solves Running a giveaway promotion manually is painful. You'd have to track every order, calculate entries, manage bonus periods, and update multipliers — sometimes at 3am when a bonus window opens or closes. Giveaway Gator handles all of this automatically. ### How It Works (The Basics) 1. **You create a promotion** with a start date, end date, and a Dollar Per Entry rate (e.g., $1 spent = 1 entry). 2. **Customers shop normally.** Every time an order is placed, Giveaway Gator automatically calculates how many entries the customer earned. 3. **Entries show up on your store.** Product pages and the thank you page display entry information so customers stay engaged. 4. **You pick a winner.** Export all entries to a CSV when the promotion ends and select your winner. ### What You Can Do With It **Drive sales without discounting:** - Award giveaway entries instead of offering percentage-off coupons - Sell entry multiplier products as virtual add-ons for extra revenue **Create urgency and excitement:** - Set up bonus periods where entries are multiplied (e.g., "40X entries this weekend!") - Display countdown timers and progress bars on your storefront - Offer spending threshold bonuses ("Spend $100+, earn 50 bonus entries") **Engage customers across channels:** - Automatically process orders from Shopify, TikTok Shop, Meta, and other channels - Let in-store POS customers claim entries from their receipts - Give customers a self-service page to check their entry totals **Stay in control:** - Add manual entries for customer service situations or special promotions - Set product-specific bonuses to spotlight featured items - View detailed audit logs showing exactly how every entry was calculated - Configure bonus discount codes that award extra entries **Re-engage and understand customers (Unlimited Pro):** - Reward post-purchase surveys to collect feedback and capture data like birthdays - Reward post-purchase actions such as social follows and referrals - Award order tag bonuses based on Shopify order tags - Restrict a promotion to specific products - Understand your audience with customer analytics and segments --- ## 2. How Entry Math Works Understanding how entries are calculated helps you design better promotions and answer customer questions. Giveaway Gator uses a layered system — each step builds on the previous one. ### Step 1: Base Entries Every promotion has a **Dollar Per Entry** setting. This is the base conversion rate. For example, if you set $1 = 1 entry, a customer who spends $50 earns 50 base entries. Each item in the order is calculated individually: item price x quantity, divided by the Dollar Per Entry rate, rounded down. ### Step 2: Product Bonuses (Multipliers & Flat Bonuses) You can set bonus multipliers or flat bonus entries on specific products. The system uses a priority hierarchy — only the highest-priority bonus applies per product: 1. **Product Bonus Periods** (highest priority) — Time-limited bonuses on specific products within a promotion. If active, these override everything below. 2. **Super Bonuses** (medium priority) — Shop-wide product bonuses set from the Shopify product admin page. Apply across all promotions. 3. **Promotion Default Multiplier** (lowest priority) — A baseline multiplier for all products in the promotion, used when no specific product bonus applies. **Important:** These don't stack. If a product has a Product Bonus Period active, the Super Bonus and Default Multiplier are ignored for that product. ### Step 3: Bonus Period Multiplier If a **Bonus Period** is active at the time of the order, entries for products *without* a specific product bonus are multiplied. For example, during a 3X bonus period, a product with 50 base entries earns 150 entries. Products that already have a product-specific bonus (from Step 2) are NOT affected by the bonus period multiplier — they use their own multiplier instead. ### Step 4: Order Bonuses (Spending Thresholds) Order bonuses reward customers for spending more. You set dollar thresholds with bonus entry amounts. For example: "Spend $100+, earn 50 bonus entries." These are flat bonus entries added on top. Order bonuses also have priority: - **Time-Period Order Bonuses** (higher priority) — Active during specific time windows. - **Promotion-Wide Order Bonuses** (lower priority) — Apply throughout the entire promotion. ### Step 5: Discount Code Bonuses If a customer uses a discount code that has bonus entries configured, those entries are added as a flat bonus. ### Step 6: Checkout Bonuses (Unlimited Pro · requires Shopify Plus) A time-limited bonus displayed during checkout. If the customer completes their purchase within the countdown, they receive extra entries. The Checkout Bonus is part of the Unlimited Pro plan and, because it displays inside checkout, requires your store to be on Shopify Plus (checkout extensions are a Shopify Plus feature). ### Step 7: Order Multiplier Products (Final Multiplier) These are virtual Shopify products that customers can purchase to multiply their entries. There are two types: - **Upgrade Multiplier** — Replaces all other multipliers. If a customer buys a 100X upgrade, their entire order uses 100X instead of whatever the current multiplier is. - **Super Multiplier** — Multiplies the final entry count *after* all other calculations. For example, if an order earned 250 entries and the customer bought a 10X Super Multiplier, they get 2,500 entries. ### Final Result After all layers are applied, the total is rounded down to a whole number. That's the customer's final entry count. ### Example Calculation A customer places a $120 order during a 3X bonus period, with a $100+ order bonus of 50 entries, using discount code "VIP10" worth 25 bonus entries: 1. **Base entries**: $120 / $1 per entry = **120 entries** 2. **Product bonuses**: No product-specific bonuses → skip 3. **Bonus period**: 3X active → 120 x 3 = **360 entries** 4. **Order bonus**: $120 meets the $100 threshold → +50 = **410 entries** 5. **Discount code**: VIP10 → +25 = **435 entries** 6. **No checkout bonus or order multiplier products** 7. **Final total: 435 entries** --- ## 3. Getting Started / Initial Setup ### Step 1: Create a Promotion 1. Open the **Giveaway Gator** app from your Shopify admin dashboard. 2. Click **Create promotion**. 3. Fill in the promotion details: - **Name**: Give your promotion a descriptive name. - **Dollar Per Entry**: Set how many dollars a customer needs to spend to earn 1 entry (e.g., $1 = 1 entry). Minimum is $1. - **Start Date & End Date**: Define when the promotion runs. - **Timezone**: Select the timezone for your promotion. If you've set a default timezone in App Preferences, it will be pre-selected. > **Important:** To include the full last day of your promotion, set the end time to **12:00 AM on the day after** the final day. For example, for a promotion ending October 31st, set the end date to November 1st at 12:00 AM. 4. Click **Create** to save your promotion. ### Step 2: Add Giveaway Gator to Your Storefront Giveaway Gator tracks entries automatically in the background — even without any theme setup, every order is processed and entries are calculated. But to show customers their entries, display countdown timers, and build excitement, you'll want to add Giveaway Gator's storefront components. #### Recommended Setup These are the components most merchants install right away: **1. Enable the Giveaway Gator App Embed** This is the engine that powers all the storefront blocks below. It runs site-wide and handles entry calculations, countdown timers, and global styling. 1. Go to **Shopify Admin > Online Store > Themes**. 2. Click **Customize** on your active theme. 3. In the left sidebar, click **App embeds** (the puzzle piece icon). 4. Toggle on **Giveaway Gator**. 5. Click **Save**. You can customize global styling here — colors, font size, border radius, and multiplier badge appearance. These settings apply to all Giveaway Gator blocks across your store. **2. Add the Giveaway Entry Tag to Product Pages** This shows customers how many entries a product is worth (e.g., "50 entries" or "50 entries 3X"). It automatically updates when a customer selects a different variant. 1. In the theme editor, go to your **product page** template. 2. Click **Add block** in the product information section. 3. Under **Apps**, select **Giveaway Entry Tag**. 4. Position it where you'd like (e.g., below the price), then **Save**. See [Displaying Entries on Product Cards](#11-displaying-entries-on-product-cards) for more details. **3. Add the Thank You Page Extension** This shows customers how many entries they just earned after completing a purchase. It activates automatically once the app is installed — you can customize it from **Shopify Admin > Settings > Checkout > Thank you page**. See [Thank You Page Entries Display](#15-thank-you-page-entries-display) for more details. **4. Add the Entry Checker** This gives customers a self-service page to look up their total entries by email. Create a page (e.g., "/pages/check-entries"), then: 1. In the theme editor, navigate to that page. 2. Click **Add block** and select **Entry Checker** under Apps. 3. Customize the title, button text, and styling, then **Save**. See [How Customers See Their Entries](#12-how-customers-see-their-entries) for more details. #### Advanced Blocks These blocks add extra engagement features. They all require the Giveaway Gator app embed to be enabled. To add any of these: in the theme editor, click **Add block** in the section where you want it, select the block under **Apps**, configure it, and **Save**. **Timer Banners** — A countdown timer showing time remaining in your promotion or bonus period. Supports 4 display styles: Inline, Banner, Floating, and Boxes. You can customize the timer template using placeholders like `${days}`, `${hours}`, `${minutes}`, `${seconds}`. See [Countdown Timer](#7-countdown-timer). **Timer Boxes** — A dedicated boxes-style countdown timer with additional layout options like label placement (inside or outside boxes), separator visibility, and independent desktop/mobile sizing. Use this instead of Timer Banners if you want more control over the boxes layout. **GG Progress Bar** — An animated progress bar that fills up as the promotion or bonus period countdown progresses. Multiple animation styles available: Pulse, Gradient Flow, Left-Right Pulse, and Glow Pulse. Can also add slanted bar overlays. See [Countdown Progress Bar](#8-countdown-progress-bar). **POS Receipt Claim** — A form for in-store POS customers to claim giveaway entries by entering their receipt number, name, and email. See [POS Claim External API](#20-pos-claim-external-api). ### Step 3: Set Up Bonus Periods (Optional) See [Bonus Periods](#4-bonus-periods-product-bonus-periods) for how to create time-limited entry multipliers. --- ## 4. Bonus Periods (Product Bonus Periods) Bonus periods let you multiply entry amounts during specific timeframes, encouraging more engagement. ### How to Set Up a Bonus Period 1. Open **Giveaway Gator** and go to **Promotions**. 2. Click **Manage** on your existing promotion. 3. Navigate to the **Bonus Periods** section. 4. Click **Add Bonus Period**. 5. Fill in the form: - **Name**: A descriptive name (e.g., "Mother's Day 40X Bonus"). - **Multiplier**: The entry multiplier (e.g., 40 means customers get 40x entries). - **Start Date & End Date**: The bonus window. - **Description**: An optional description. 6. Click **Save**. > **Important:** To include the full last day of your bonus period, set the end date to **12:00 AM on the day after** the final day. For example, for a bonus ending July 12th, set the end date to July 13th at 12:00 AM. ### Verify the Multiplier After saving, refresh your product page. The entries tag should reflect the new multiplier (e.g., "40X" instead of "1X"). --- ## 5. Order Bonuses Order bonuses multiply the total entries for an entire order based on spending thresholds. This encourages customers to spend more. ### How to Set Up Order Bonuses 1. Log in to **Giveaway Gator** and go to **Promotions**. 2. Click **Manage** on your promotion. 3. Navigate to the **Order Bonuses** section. 4. Set bonus period dates — ensure they align with your promotion duration. > **Note:** To cover the entire last day, set the end date to the day *after* the final day. For example, for a promotion ending October 1st, set the bonus period to end on October 2nd. 5. Click **Create** to save the bonus period settings. 6. **Verify**: Refresh your product page to confirm the multiplier (e.g., "50x") is displaying correctly. --- ## 6. Order Bonus Progress Bar The order bonus progress bar shows customers how close they are to reaching the next order bonus threshold. > **Note:** This documentation is under construction. ### Theme-Based Carts 1. Ensure **"Order Bonuses"** is enabled in the **"Giveaway Gator Body Embed"** theme embed. 2. Add this snippet to your theme cart to render the progress bar: ```html
``` ### Using with Slide Cart by Amp ```html ``` ### Customizing the Progress Bar The progress bar can be styled with CSS. Key classes include: - `.gg-order-bonuses-container` — Main container - `.gg-progress-bar-background` — Progress bar track - `.gg-progress-bar-fill` — Progress bar fill - `.gg-threshold-badge` — Individual threshold badges - `.gg-threshold-badge.active` — Reached threshold badges - `.gg-next-threshold-message` — "Spend $X more" message --- ## 7. Countdown Timer Countdown timers create urgency by showing customers how much time remains in your promotion or bonus period. ### Prerequisites 1. Enable the **Giveaway Gator Body Tag** in your theme's App Embeds. ### Basic Implementation Add this HTML element anywhere in your theme: ```html
``` ### Customization Options **Data Attributes:** - `data-gg-countdown-timer` (required) — Initializes the timer. - `data-template` (optional) — Custom display format. - Default: `${days}d ${hours}h ${minutes}m ${seconds}s` - Variables: `${days}`, `${hours}`, `${minutes}`, `${seconds}`, `${multiplier}`, `${multiplierX}` - `data-style` (optional) — Display style (default: `inline`). ### Example Templates ```html
``` ### CSS Styling ```css .gg-countdown-timer { --gg-timer-bg: #f3f4f6; --gg-timer-text: #111827; --gg-timer-font-size: 16px; --gg-timer-border-radius: 4px; } ``` ### Behavior Notes - Auto-updates every second - Revalidates every 5 minutes for accuracy - Auto-hides when countdown reaches zero - Shows bonus multipliers when active - Prioritizes bonus period countdowns over regular giveaway end times --- ## 8. Countdown Progress Bar The countdown progress bar is a visual component that transforms countdown timers into animated progress bars. ### Key Features - **Minimum 50% fill** — never looks empty - **Smart progress**: 50% baseline at 4+ days, linear to 100% in final 4 days - **5 animation types**: None, Pulse, Gradient Flow, Left to Right Pulse, Glow Pulse - **Slanted bars overlay** with customizable width and speed - **Shadow & glow effects** with color and intensity control ### Implementation Methods **Method 1: Theme Editor Block** Add the "GG Progress Bar" block in the Shopify theme editor. No code required. **Method 2: Custom Liquid (Class-Based)** ```html
``` **Method 3: Page Builder (Attribute-Based)** ```html
``` ### CSS Variables ```css /* Core */ --gg-progress-height: 20px; --gg-progress-border-radius: 10px; --gg-progress-start-color: #ef4444; --gg-progress-end-color: #dc2626; --gg-progress-bg: #e5e7eb; /* Animation */ --gg-animation-speed: 2s; --gg-slanted-speed: 1.5s; --gg-slanted-width: 8px; /* Shadow & Glow */ --gg-progress-shadow: 0 0 20px #ff0000; --gg-glow-color: #ff0000; ``` ### Page Builder Integration Works with PageFly, GemPages, Shogun, and LayoutHub — use their HTML/Custom Code blocks. --- ## 9. Bonus Discount Codes Bonus discount codes award extra entries when customers use specific codes at checkout. ### How to Set Up 1. Log in to **Giveaway Gator** and go to **Discount Codes > Add Discount Codes**. 2. Fill in the details: - **Discount Code**: The code customers will use (e.g., "FREESHIPPING25"). - **Usage Limit**: Leave blank for unlimited or set a max. - **Bonus Entries**: The number of bonus entries the code awards. 3. Click **Add** to save and activate. ### Managing Codes View and manage codes in the **Discounts tab** in your Shopify admin. --- ## 10. Order Multiplier Products Order Multiplier Products are virtual Shopify products that your customers can add to their cart to multiply their giveaway entries. Instead of giving away bonus entries for free, you can **sell** multipliers — turning your giveaway into a revenue driver. ### Two Types of Multipliers **Upgrade Multiplier** - **Replaces** the current multiplier for the entire order - All other bonuses are skipped (product bonuses, bonus periods, order bonuses, discount codes) - Example: Customer orders during a 25X bonus period and buys a "100X Upgrade" — entire order earns at 100X instead of 25X **Super Multiplier** - **Multiplies the final entry count** after all other calculations - Stacks on top of everything - Example: Customer earns 250 entries normally, buys a "10X Super Multiplier" — final total becomes 2,500 entries ### Setting Up 1. Open **Giveaway Gator** in your Shopify admin. 2. Go to **Order Multipliers** from the navigation. 3. Click **Create Multiplier Product**. 4. Fill in: Product Name, Multiplier Value (minimum 2), Multiplier Type (Upgrade or Super). 5. Click **Create**. You can also configure an existing Shopify product as a multiplier using the **Configure Existing Product** option. ### Managing Multiplier Products - **Edit** the multiplier value - **Publish/unpublish** — Toggle availability (ACTIVE/DRAFT in Shopify) - **Delete** — Removes from both Giveaway Gator and Shopify ### How It Affects Calculations Multiplier products are excluded from the base entry calculation — their price doesn't count toward dollar-per-entry math. - **Upgrade Multiplier**: Base Entries × Upgrade Multiplier (skips all other bonuses) - **Super Multiplier**: Normal Total × Super Multiplier (applied at the very end) ### Tips - Price multipliers strategically — a $5 product for 10X entries feels like a great deal - Use Upgrade Multipliers for simplicity, Super Multipliers for stacking power - Only one multiplier per type applies per order (highest value used) - Multiplier products appear in audit logs --- ## 11. Displaying Entries on Product Cards The `gg-entry-tag` displays entry calculations on product cards throughout your store. ### What It Shows - **Base entries** based on product price and dollar-per-entry setting - **Bonus entries** from product bonuses, multipliers, or bonus periods - **Visual indicators** like "2X" badges for multipliers ### Prerequisites 1. Giveaway Gator app installed and configured 2. Active promotion with products selected 3. App embed enabled in your theme ### Add via the Theme Editor (No Code) On product pages, and on collection product cards in Horizon and other newer Online Store 2.0 themes, add the **Giveaway Entry Tag** app block directly in the theme editor — no code: 1. Go to **Online Store > Themes > Customize**. 2. Open the product page template, or select your collection's product card / product grid section. 3. Click **Add block**, then under **Apps** choose **Giveaway Entry Tag**. 4. Position it, style it, and **Save**. On collection cards the block automatically reads each card's product. Each block offers a Display style (Minimal or Detailed), an optional custom-colors override, font size, and border radius. ### Quick Start (Older Themes — Code Snippet) If your theme doesn't support app blocks on product cards, add this HTML snippet to your product card template: ```html
``` > **Important:** Make sure the product variable (e.g., `card_product`) matches what your theme uses in the same snippet or section. ### Common Template Locations - `snippets/product-card.liquid` - `snippets/card-product.liquid` - `sections/collection-template.liquid` - `sections/main-collection.liquid` ### Variant Support Include variant data for automatic price updates when customers select different variants: ```html
``` Variant updates work automatically via URL parameter watching and DOM selector watching. ### CSS Customization ```css .gg-entry-tag { --gg-tag-bg: #f4f4f4; --gg-tag-text: #333333; --gg-tag-accent: #000000; --gg-tag-bonus: #17a2b8; --gg-tag-font-size: 16px; --gg-tag-border-radius: 4px; } .gg-entry-multiplier { --gg-tag-multiplier-bg: #059669; --gg-tag-multiplier-text: #ffffff; --gg-tag-multiplier-radius: 4px; } ``` > **Tip:** It's best to use the style settings in the App Embed settings to keep things consistent across your store. ### Testing Entry Tags Open your browser console and run: ```javascript window.GiveawayGator.test(); // Enable test mode window.GiveawayGator.test(false); // Disable test mode ``` ### Troubleshooting **Entry tag not showing:** - Verify the app embed is enabled in your theme - Check that `window.GiveawayGator` exists in the browser console - Ensure all required attributes are present (`class`, `data-gg-entry-tag`, `data-product-id`, `data-price`) - Verify inner spans exist (`gg-entry-total`, `gg-entry-bonus`) **Shows "0 entries":** - Check the app embed is enabled - Verify the product liquid variable matches the rest of the section - Check that `data-price` has a valid number - Verify the dollar-per-entry setting in your promotion **Variants not updating:** - Ensure `data-variants` attribute is present - Check that variant data is properly base64-encoded --- ## 12. How Customers See Their Entries Customers can check their total entries via a dedicated "Check Your Entries" page. ### Setup 1. Create a **page template** in your Shopify theme for the entries page. 2. Add the **"Check Entries Form"** block to the template. 3. Customize the styling to match your brand. --- ## 13. Exporting Entries ### How to Export 1. Open **Giveaway Gator** from your Shopify dashboard. 2. Find the promotion and click **Entries > View Entries**. 3. Click the **Export All Entries** button (top right corner). 4. A CSV file will automatically download. ### CSV Contents - Order number - Date created - Amount spent - Total number of entries - Log of items purchased --- ## 14. Manual Entries ### How to Add Manual Entries (In-App) 1. Open **Giveaway Gator** and select the promotion. 2. Click **Manage** to open the promotion details. 3. Navigate to the **Entries** section. 4. Click the **Manual Entry** button. 5. Fill in: - **Email Address**: Customer's email. - **Reason**: Why you're adding the entry (e.g., "Bonus for special promotion"). - **Number of Entries**: How many entries to add. 6. Click **Add Entry**. The manual entry will appear in the Entries list with "MANUAL" as the order number. --- ## 15. Thank You Page Entries Display Display total entries earned on the order confirmation (thank you) page. Setup is done via the Shopify theme editor — add the Giveaway Gator thank you page extension. *(Video walkthrough available in the app documentation.)* --- ## 16. Test Mode - Preview Before Going Live There are two ways to preview your storefront before a real giveaway is running. ### Preview Mode (Theme Editor — No Code) In the theme editor, open **App embeds**, expand **Giveaway Gator**, and check **Preview mode**. Your entry tags and countdown timer fill with sample data so you can style them even when no giveaway is active. It affects only the theme editor preview — never your live storefront. Uncheck it when you're done. ### Storefront Test Mode (Advanced) For a deeper test on your live storefront, the `window.GiveawayGator.test()` browser-console tool simulates active promotions without configuring real ones. ### Basic Usage ```javascript // Enter test mode with defaults window.GiveawayGator.test() // Enter test mode with custom config window.GiveawayGator.test({ dollarPerEntry: 10, entryCalculation: { bonusPeriod: { multiplier: 5, endTime: "2025-07-07T12:00:00" } } }) // Exit test mode window.GiveawayGator.test(false) ``` ### Default Test Configuration - Active promotion ending in 7 days - Bonus period ending in 2 days with 3x multiplier - $5 per entry conversion rate - Sample product bonuses ### Features - Orange "TEST MODE" badge in top-right corner - Persists across page navigation (via sessionStorage) - Auto-expires after 2 hours - All components (entry tags, countdown timers) update immediately - Original configuration is preserved and restored on exit ### Configuration Options | Property | Type | Description | |----------|------|-------------| | `dollarPerEntry` | Number | How much money = 1 entry | | `entryCalculation.bonusPeriod.multiplier` | Number | Entry multiplier during bonus period | | `entryCalculation.bonusPeriod.endTime` | String (ISO) | When bonus period ends | | `entryCalculation.defaultMultiplier` | Number | Default entry multiplier | | `entryCalculation.productBonuses` | Object | Product-specific bonuses | --- ## 17. Product Bonuses Admin Block (Shopify Admin) Configure Super Bonuses directly from your Shopify product pages — no need to switch apps. ### Capabilities **Entry Multiplier:** - Set a multiplier for base giveaway entries (e.g., 3 = 3x entries for this product) - Perfect for featured products, new launches, high-margin items **Flat Bonus Entries:** - Add a fixed bonus amount when product is purchased (e.g., +50 extra entries) - Perfect for VIP products, bundle incentives, clearance items ### How to Use 1. Navigate to any **product page** in Shopify Admin. 2. Scroll to the **"Giveaway Gator Super Bonuses"** block. 3. Click **"Add Super Bonus"**. 4. Enter values: - Entry Multiplier (e.g., `2` for double entries) - Bonus Entries (e.g., `100` for 100 extra entries) 5. **Save** — bonuses are live immediately. ### Configuration Tips - Set to `0` to disable without deleting - Clear fields to completely remove bonuses - Integer values only - Changes apply to ALL active promotions - Effect is immediate for new orders --- ## 18. Order Entries Admin Extensions (Shopify Admin) View giveaway entries and audit logs directly in the Shopify order detail page. ### Order Entries Block - Appears on Shopify order detail pages - Shows total entry count across all active promotions - Displays individual promotion breakdown ### Order Entries Audit Action - Triggered via "View Audit Logs" button - Shows complete entry calculation audit trail: - Promotion Details (name, dates, conversion rate) - Entry Calculations (line-by-line) - Multipliers applied - Bonus Periods checked - Product Bonuses applied - Order Bonuses applied - Final Result with total entries ### Use Cases - **Customer inquiries**: Instantly see how many entries an order received - **Troubleshooting**: Detailed audit logs show exact calculation steps - **Promotion analysis**: Verify multipliers and bonuses are working correctly These extensions deploy automatically with the Giveaway Gator app — no additional setup required. --- ## 19. Manual Entries API For integrating Giveaway Gator with other systems (loyalty programs, third-party apps). ### Endpoint ``` POST /api/v2/promos/[id]/manual-entry Content-Type: multipart/form-data Auth Required: Yes ``` ### Request Fields | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Entrant's full name | | `email` | string | Yes | Entrant's email address | | `entries` | number | Yes | Number of entries (minimum: 1) | | `reason` | string | Yes | Reason for the manual entry | ### Example ```bash curl -X POST \ https://giveawaygator.app/api/v2/promos/123/manual-entry \ -H 'Content-Type: multipart/form-data' \ -F 'name=John Doe' \ -F 'email=john@example.com' \ -F 'entries=10' \ -F 'reason=Customer service adjustment' ``` ### Response **Success (200):** ```json { "success": true, "message": "Manual entry created" } ``` **Error (400):** ```json { "success": false, "message": "Missing required fields" } ``` ### Notes - Entry appears with "MANUAL" as the order number - Audit log shows the reason and total entries - Timestamps use UTC --- ## 20. POS Claim External API Allow customers to claim giveaway entries from POS (Point of Sale) receipts. ### Endpoint ``` POST /api/theme/pos-claim?shop={shop_domain} Content-Type: application/json ``` ### Authentication - **Theme embed**: Automatic via Shopify app proxy signature - **Custom integration**: `Authorization: Bearer {GIVEAWAY_GATOR_API_KEY}` ### Rate Limits - Theme embed: 10 requests/minute per IP - API key: 60 requests/minute per key ### Request Body ```json { "receiptNumber": "POS12345", "email": "customer@example.com", "firstName": "Ada", "lastName": "Lovelace" } ``` All fields are required. ### Response ```json { "status": "success", "orderId": "gid://shopify/Order/123456789", "orderName": "#1001", "entriesAwarded": 15, "claimedAt": "2025-01-05T22:41:03.123Z", "promotions": [ { "promoId": "promo-uuid", "promoName": "Holiday Giveaway", "entriesAwarded": 15, "alreadyClaimed": false, "claimedAt": "2025-01-05T22:41:03.123Z" } ] } ``` **Status Values:** - `success` — Entries awarded - `already_claimed` — All promotions already claimed - `no_active_promotions` — Order found but no active promos - `not_found` — No matching order - `error` — Unexpected failure ### Theme Embed Example ```html
``` ### Best Practices - Always include the `shop` query parameter - Store API keys securely and rotate if compromised - Ensure orders are ingested into Giveaway Gator before claiming - Consider CAPTCHA for front-end forms to reduce abuse --- ## 21. FAQs ### How are entries calculated? Entries are calculated automatically when an order is placed. The system uses a layered approach — see the detailed breakdown in [Section 2: How Entry Math Works](#2-how-entry-math-works). In short: base entries come from the Dollar Per Entry rate (e.g., $1 = 1 entry), then product bonuses, bonus period multipliers, order bonuses, discount code bonuses, and order multiplier products are applied in sequence. Each layer builds on the previous one. ### Do entries sync automatically? Yes. Giveaway Gator automatically processes new orders and calculates entries in real-time. No manual sync is needed. ### What about post-purchase upsells? Post-purchase upsell orders are processed automatically. The upsell amount is included in the entry calculation just like a regular order. ### How can customers check their entries? Customers can visit a dedicated "Check Your Entries" page on your store. You set this up by creating a page template and adding the "Check Entries Form" block. ### What about TikTok Shop and Meta orders? Orders from TikTok Shop and Meta that sync to Shopify are processed automatically. As long as the order appears in your Shopify admin, Giveaway Gator will calculate entries for it. ### Can I add manual entries? Yes. You can add manual entries from within the app (Promotion > Entries > Manual Entry) or via the Manual Entries API for system integrations. ### My entry badges are showing 0 — what's wrong? This is usually caused by: 1) The app embed not being enabled — toggle it on in Online Store > Themes > Customize > App embeds. 2) A product variable mismatch — the entry tag uses a variable like `card_product.id` which must match your theme's variable. 3) An empty or invalid `data-price` attribute. 4) No active promotion. See [Section 11: Displaying Entries on Product Cards](#11-displaying-entries-on-product-cards) for full troubleshooting steps. ### Entry tags stopped working after a theme update — what should I do? Theme updates can overwrite custom code. Check that the entry tag snippet is still in your product card template, verify the product variable still matches, and make sure the app embed is still enabled. Contact support for free reinstallation help. ### Entries aren't syncing automatically — how do I fix this? Check webhook status in Giveaway Gator > Settings and use detach/reattach to reset if needed. Verify you have an active promotion, and try a manual resync. Webhooks are self-healing but may need a manual reset after platform updates. ### Can I run more than one promotion at the same time? Yes. Every order earns entries in all active promotions automatically. Keep bonus period multipliers aligned across promotions so product entry tags display correctly. See [Section 7: Running Multiple Promotions](#7-running-multiple-promotions) in the docs. ### Does Giveaway Gator work with subscription apps? Yes. Subscription orders are processed like any Shopify order. For fixed bonus entries per subscription, set the product multiplier to 0 and add a bonus entry amount instead. ### Which features require Shopify Plus? Most features work on every Shopify plan. The only one that needs Shopify Plus is the Checkout Bonus (showing entries inside checkout), because checkout extensions are a Shopify Plus feature; it's part of Unlimited Pro. The thank-you page extension, entry tags, countdown timers, Entry Checker, and everything else work on every Shopify plan. Note: "Shopify Plus" is your store's Shopify subscription, separate from your Giveaway Gator plan (Unlimited or Unlimited Pro). ### What plans does Giveaway Gator offer? Two plans, both with unlimited orders and entries, in-app live chat support, and a 1:1 onboarding session: - **Unlimited ($199/month)** — every giveaway and storefront feature: promotions, bonuses, multipliers, storefront blocks, POS claims, Shopify Flow, and the API. - **Unlimited Pro ($299/month)** — everything in Unlimited, plus customer analytics, post-purchase surveys, post-purchase actions, the Checkout Bonus, product restricted promotions, and order tag bonuses. See [Section 24: Plans & Pricing](#24-plans--pricing). ### What support is included? Both plans include in-app live chat support and a 1:1 onboarding session, plus email support at support@support.giveawaygator.app. --- ## 22. Post-Purchase Surveys (Unlimited Pro) Reward customers with bonus entries for answering a short survey after they buy — to collect feedback, measure satisfaction (rating and NPS), capture birthdays, and learn who your customers are. ### Setup 1. Open **Giveaway Gator > Surveys** and click **Create survey**. 2. Set a **title**, **description**, and **entry reward** (default 100). 3. Add questions. Types: single choice, multiple choice, short text, long text, rating (1–5), NPS (0–10), and birthday. Each question can be required, can randomize its options, and can apply a customer tag from the answer. 4. Save as a draft, then switch the status to **active**. Once active, it automatically appears on the thank-you page and the order status page for every promotion — placement and audience are handled for you. ### Reviewing results Open a survey and click **Results** for total responses, completion rate, impressions, and entries awarded. Each question shows a fitting breakdown (bar charts, average rating, NPS with Promoter/Passive/Detractor split, paged text answers, birthday distribution). Filter by audience **segments** (presets like New entrants, Repeat purchasers, Loyalists, High spenders, plus custom rules), **compare two segments** side by side, filter by date, and **export** all responses to CSV. Each customer can complete a survey once; answering on one page means it won't ask again on the other. --- ## 23. Post-Purchase Actions (Unlimited Pro) Give customers more ways to earn entries after checkout — buttons on the thank-you page that reward social follows, custom actions, and (coming soon) referrals. ### Action types - **Social Visit** — Facebook, Instagram, TikTok, or a custom link. Set a button label, the link, and the entry reward. The link opens in a new tab and entries are awarded. - **Custom Webhook** — connect an outside service that confirms the action and awards entries. Requires an API key, configured under Settings. - **Referral** — coming soon. ### Setup 1. Open **Giveaway Gator > Post-Purchase Actions** and click **Create action**. 2. Choose the type, set the **button label**, **link**, and **entry reward**. 3. Choose **Once per User** (Global) or **Once per Order** (awards again on each new order the customer completes). 4. Save and toggle it **on**. Actions are shared across your store, so they appear on the thank-you page for every promotion. Only actions you've turned on are shown. --- ## 24. Plans & Pricing Two plans, both with unlimited orders and entries, in-app live chat support, a 1:1 onboarding session, and a free trial. ### Unlimited — $199/month Every giveaway and storefront feature: promotions, bonus periods, super bonuses, order bonuses, bonus discount codes, order multiplier products, all storefront blocks (entry tags, countdown timers, progress bars, Entry Checker), thank-you and order status entry displays, the order confirmation email image, POS receipt claims, Shopify Flow, the REST API, manual entries, CSV export, and audit logs. ### Unlimited Pro — $299/month Everything in Unlimited, plus: - **Customer analytics** — cohort and segment insights on your Customers page - **Post-purchase surveys** (Section 22) - **Post-purchase actions** (Section 23) - **Checkout Bonus** — entries inside checkout and fast-checkout rewards (requires your store to be on Shopify Plus) - **Product restricted promotions** — limit a promotion to specific products - **Order tag bonuses** — award entries based on Shopify order tags Change plans anytime under **Giveaway Gator > Settings**. --- ## Known Issues & Notes ### Duplicate Documentation Pages - "How to Get Setup?" and "How to Set Up?" were near-duplicate pages in Notion. Content has been consolidated into Section 2 above. ### Pages Marked Under Construction - **Order Bonus Progress Bar** documentation is marked as "under construction" in Notion. ### Pages with Video-Only Content - **Thank You Page** documentation (Section 13) had only a video walkthrough with no text content. --- *Last compiled: June 29, 2026*