> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ecomelixir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Offer and urgency blocks

> Free gifts, upsells, countdown timers, and stock urgency blocks for the product page

Every setting below is read directly from the theme's block schema, so the names match exactly what you see in the Shopify theme editor. Settings are listed by their internal ID with the editor label beside them.

Add these in the theme editor on your product page, inside the **Product Details** container or directly in the product section.

### Free Gift

Block ID `pdp-free-gift`.

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `unlock_type` | select | `quantity`, `value`, `subscription` / default `quantity` | Unlock Type *(Gift Products)*. Choose how gifts unlock: by quantity added, by product value in cart, or by choosing a subscription. |
| `gift_product_1` | product | | Gift Product 1 *(Gift Products)*. |
| `threshold_1` | range | default `2` | Unlock at (quantity) *(Gift Products)*. |
| `value_threshold_1` | text | default `20` | Unlock at (value) *(Gift Products)*. Product value (quantity x price) needed to unlock, in your store currency. Enter a number only. |
| `gift_product_2` | product | | Gift Product 2 *(Gift Products)*. |
| `threshold_2` | range | default `3` | Unlock at (quantity) *(Gift Products)*. |
| `value_threshold_2` | text | default `50` | Unlock at (value) *(Gift Products)*. |
| `gift_product_3` | product | | Gift Product 3 *(Gift Products)*. |
| `threshold_3` | range | default `4` | Unlock at (quantity) *(Gift Products)*. |
| `value_threshold_3` | text | default `80` | Unlock at (value) *(Gift Products)*. |
| `gift_product_4` | product | | Gift Product 4 *(Gift Products)*. |
| `threshold_4` | range | default `5` | Unlock at (quantity) *(Gift Products)*. |
| `value_threshold_4` | text | default `100` | Unlock at (value) *(Gift Products)*. |
| `title_richtext` | richtext | default `<p>Get a <strong>free gift</strong></p>` | Title *(Title)*. |
| `subtitle_progress` | richtext | default `<p>Purchase {quantity} {name} to unlock</p>` | Subtitle (in progress) *(Title)*. Shown while gifts are still locked. Use \{quantity} for the amount left to add and \{name} for the product name. |
| `subtitle_unlocked` | richtext | default `<p>All free gifts unlocked</p>` | Subtitle (all unlocked) *(Title)*. Shown once every gift is unlocked. |
| `show_title_icon` | checkbox | default `False` | Show Title Icon *(Title)*. Only shown in the list layout (3 or more gifts). |
| `title_icon` | image\_picker | | Title Icon *(Title)*. |
| `content_alignment` | text\_alignment | default `left` | Alignment *(Title)*. |
| `show_banner` | checkbox | default `False` | Show Top Banner *(Top Banner)*. |
| `banner_text` | richtext | default `<p>Limited time offer</p>` | Banner Text *(Top Banner)*. |
| `typography_sizing_mode` | select | `preset`, `custom` / default `preset` | Typography sizing *(Typography Sizing)*. Preset uses the built-in font sizes. Switch to Custom to fine-tune sizes. |
| `spacing_mode` | select | `preset`, `custom` / default `preset` | Spacing *(Spacing)*. Preset uses the built-in spacing. Switch to Custom to fine-tune spacing. |

Plus 34 appearance settings (colors, sizes, spacing).

### Free Gifts Progress

Block ID `pdp-free-gifts-progress`.

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `unlock_type` | select | `quantity`, `value`, `subscription` / default `quantity` | Unlock Type *(Gift Products)*. Choose how gifts unlock: by quantity added, by product value in cart, or by choosing a subscription. |
| `gift_product_1` | product | | Gift Product 1 *(Gift Products)*. |
| `threshold_1` | range | default `2` | Unlock at (quantity) *(Gift Products)*. Units of this product needed to unlock Gift 1. |
| `value_threshold_1` | text | default `20` | Unlock at (value) *(Gift Products)*. Product value (quantity × price) needed to unlock Gift 1, in your store currency. Enter a number only. |
| `gift_product_2` | product | | Gift Product 2 *(Gift Products)*. |
| `threshold_2` | range | default `3` | Unlock at (quantity) *(Gift Products)*. |
| `value_threshold_2` | text | default `50` | Unlock at (value) *(Gift Products)*. |
| `gift_product_3` | product | | Gift Product 3 *(Gift Products)*. |
| `threshold_3` | range | default `4` | Unlock at (quantity) *(Gift Products)*. |
| `value_threshold_3` | text | default `80` | Unlock at (value) *(Gift Products)*. |
| `gift_product_4` | product | | Gift Product 4 *(Gift Products)*. |
| `threshold_4` | range | default `5` | Unlock at (quantity) *(Gift Products)*. |
| `value_threshold_4` | text | default `100` | Unlock at (value) *(Gift Products)*. |
| `title_richtext` | richtext | default `<p><strong>Free Gifts</strong></p>` | Title *(Title)*. |
| `subtitle_progress` | richtext | default `<p>Purchase {quantity} {name} to unlock</p>` | Subtitle (in progress) *(Title)*. Shown while gifts are still locked. Use \{quantity} for the amount left to add and \{name} for the product name. |
| `subtitle_unlocked` | richtext | default `<p>All free gifts unlocked</p>` | Subtitle (all unlocked) *(Title)*. Shown once every gift is unlocked. |
| `show_title_icon` | checkbox | default `False` | Show Title Icon *(Title)*. |
| `title_icon` | image\_picker | | Title Icon *(Title)*. |
| `content_alignment` | text\_alignment | default `left` | Alignment *(Title)*. |
| `show_progress_bar` | checkbox | default `True` | Show Progress Bar *(Progress Bar)*. |
| `customize_progress_size` | checkbox | default `False` | Customize Bar Size *(Progress Bar)*. |
| `typography_sizing_mode` | select | `preset`, `custom` / default `preset` | Typography sizing *(Typography Sizing)*. Preset uses the built-in font sizes. Switch to Custom to fine-tune sizes. |
| `spacing_mode` | select | `preset`, `custom` / default `preset` | Spacing *(Spacing)*. Preset uses the built-in spacing. Switch to Custom to fine-tune spacing. |

Plus 28 appearance settings (colors, sizes, spacing).

### Product Upsell

Block ID `pdp-product-upsell`.

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `upsell_product` | product | | Upsell product *(Product)*. |
| `target_variant` | text | | Show only for variant *(Conditional display)*. Enter a variant option value (e.g. Small) or multiple values separated by slashes (e.g. Small / Red). The block shows only when the selected main product variant matches all parts. Leave blank to always show. |
| `use_custom_title` | checkbox | default `False` | Use custom title *(Content)*. When off, the product's own title is shown. |
| `custom_title` | text | | Custom title *(Content)*. |
| `make_title_clickable` | checkbox | default `False` | Make title a link to the product page *(Content)*. |
| `show_description` | checkbox | default `False` | Show description *(Content)*. |
| `description_text` | textarea | default `Short product description here` | Description *(Content)*. |
| `show_badge` | checkbox | default `False` | Show badge *(Content)*. |
| `badge_text` | text | default `BEST SELLER` | Badge text *(Content)*. |
| `badge_svg` | textarea | | Badge icon (SVG code, optional) *(Content)*. Paste custom SVG code to show an icon in the badge. Leave blank for the default medal icon. |
| `button_style` | select | `button`, `toggle` / default `button` | Button style *(Add button)*. |
| `cart_action` | select | `drawer`, `bulk` / default `drawer` | Behaviour *(Add button)*. Open cart drawer adds the item right away and opens the cart. Add with product stages it so it is added together when the customer clicks the main add to cart button. |
| `button_text` | text | default `Add +` | Button text *(Add button)*. |
| `added_text` | text | default `Added` | Button text after adding *(Add button)*. |
| `show_custom_icon` | checkbox | default `False` | Show icon in button *(Add button)*. |
| `custom_icon_svg` | textarea | | Button icon SVG code *(Add button)*. |
| `typography_sizing_mode` | select | `preset`, `custom` / default `preset` | Font size *(Typography)*. Preset uses sensible defaults. Switch to Custom to set your own sizes. |
| `spacing_mode` | select | `preset`, `custom` / default `preset` | Advanced spacing *(Spacing and border)*. Switch to Custom to control margins, corner radii, and button size. |
| `border_style` | select | `none`, `solid`, `dashed`, `dotted` / default `solid` | Border style *(Spacing and border)*. |

Plus 33 appearance settings (colors, sizes, spacing).

### Deal Timer

Block ID `pdp-deal-timer`.

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `background_type` | select | `solid`, `gradient` / default `solid` | Background Type *(Color & Style)*. |
| `enable_block_border` | checkbox | default `False` | Enable Block Border *(Layout Settings)*. |
| `block_border_style` | select | `solid`, `dashed`, `dotted` / default `solid` | Border Style *(Layout Settings)*. |
| `show_separator` | checkbox | default `False` | Show Separator Line *(Layout Settings)*. |
| `show_deal_text` | checkbox | default `True` | Show Deal Text *(Content)*. |
| `deal_title` | text | default `$20 OFF` | Deal Title *(Content)*. |
| `show_subtitle` | checkbox | default `True` | Show Subtitle *(Content)*. |
| `deal_subtitle` | text | default `Limited Time Deal` | Deal Subtitle *(Content)*. |
| `show_countdown` | checkbox | default `True` | Show Countdown *(Countdown Timer)*. |
| `end_date` | text | default `2028-12-31 23:59:59` | End Date & Time *(Countdown Timer)*. Format: YYYY-MM-DD HH:MM:SS (e.g., 2026-12-31 23:59:59) |
| `expiry_behavior` | select | `zeros`, `hide`, `message` / default `zeros` | When Timer Runs Out *(Countdown Timer)*. |
| `expired_message` | text | default `This offer has ended.` | Expired Message *(Countdown Timer)*. |
| `show_discount_code` | checkbox | default `False` | Show Discount Code *(Discount Code)*. |
| `discount_code` | text | default `BF0Z20` | Discount Code *(Discount Code)*. |
| `button_text` | text | default `COPY` | Button Text *(Discount Code)*. |
| `spacing_mode` | select | `preset`, `custom` / default `preset` | Spacing *(Spacing)*. |
| `typography_sizing_mode` | select | `preset`, `custom` / default `preset` | Typography *(Typography)*. |

Plus 36 appearance settings (colors, sizes, spacing).

### Selling Out Fast

Block ID `pdp-selling-out-fast`.

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `main_text` | text | default `SELLING OUT FAST` | Main text *(Content)*. |
| `subtitle_text` | text | default `Due to high demand, limited quantities available` | Subtitle text *(Content)*. |
| `text_alignment` | select | `left`, `center`, `right` / default `center` | Text alignment *(Content)*. |
| `show_icon` | checkbox | default `False` | Show icon before title *(Content)*. |
| `icon_type` | select | `fire`, `info`, `custom` / default `fire` | Icon type *(Content)*. Choose a predefined icon or use custom SVG |
| `custom_icon_svg` | textarea | | Custom SVG code *(Content)*. Only used when 'Custom SVG' is selected. Paste your SVG code here. |
| `icon_size` | range | default `18` | Icon size (px) *(Content)*. |
| `progress_percentage` | range | default `87` | Progress percentage *(Progress Bar)*. Percentage of product sold (0-100%). Used for the single bar. |
| `progress_text` | text | default `SOLD` | Progress text *(Progress Bar)*. Text shown after percentage (e.g., '87% SOLD') |
| `progress_text_overlay` | checkbox | default `True` | Show progress text on top of progress bar *(Progress Bar)*. |
| `progress_bar_height` | range | default `20` | Bar height (px) *(Progress Bar)*. |
| `border_radius` | range | default `8` | Bar border radius (px) *(Progress Bar)*. |
| `progress_bar_gradient` | checkbox | default `False` | Use gradient *(Progress Bar)*. |
| `enable_striped` | checkbox | default `False` | Striped bar *(Progress Bar)*. Adds diagonal stripes over the progress bar fill. |
| `striped_animated` | checkbox | default `True` | Animate stripes *(Progress Bar)*. |
| `show_progress_border` | checkbox | default `False` | Show bar border *(Progress Bar)*. |
| `progress_border_width` | range | default `2` | Bar border width (px) *(Progress Bar)*. |
| `enable_multiple_bars` | checkbox | default `False` | Enable multiple progress bars *(Multiple Progress Bars)*. Show multiple bars with different titles and percentages instead of a single bar. |
| `bars_gap` | range | default `8` | Gap between bars (px) *(Multiple Progress Bars)*. |
| `bar_title_size` | range | default `12` | Bar title font size (px) *(Multiple Progress Bars)*. |
| `bar1_title` | text | default `October 8th` | Bar 1 - Title *(Multiple Progress Bars)*. Leave blank to hide this bar |
| `bar1_percentage` | range | default `100` | Bar 1 - Percentage *(Multiple Progress Bars)*. |
| `bar1_status` | text | default `SOLD OUT` | Bar 1 - Status text *(Multiple Progress Bars)*. |
| `bar2_title` | text | default `October 25th` | Bar 2 - Title *(Multiple Progress Bars)*. Leave blank to hide this bar |
| `bar2_percentage` | range | default `70` | Bar 2 - Percentage *(Multiple Progress Bars)*. |
| `bar2_status` | text | default `70% SOLD` | Bar 2 - Status text *(Multiple Progress Bars)*. |
| `bar3_title` | text | default `November 11th` | Bar 3 - Title *(Multiple Progress Bars)*. Leave blank to hide this bar |
| `bar3_percentage` | range | default `0` | Bar 3 - Percentage *(Multiple Progress Bars)*. |
| `bar3_status` | text | default `0% sold` | Bar 3 - Status text *(Multiple Progress Bars)*. |
| `show_background` | checkbox | default `True` | Show background *(Background)*. |
| `padding` | range | default `12` | Internal padding (px) *(Background)*. |
| `block_border_radius` | range | default `8` | Corner radius (px) *(Background)*. |
| `show_block_border` | checkbox | default `False` | Show border *(Block Border)*. |
| `block_border_width` | range | default `2` | Border width (px) *(Block Border)*. |
| `main_text_size` | range | default `14` | Main text size (px) *(Typography)*. |
| `subtitle_text_size` | range | default `13` | Subtitle text size (px) *(Typography)*. |
| `progress_text_size` | range | default `11` | Progress text size (px) *(Typography)*. |
| `overlay_text_size` | range | default `11` | Overlay text size (px) *(Typography)*. |
| `margin_top` | range | default `15` | Top margin (px) *(Layout)*. |
| `margin_bottom` | range | default `15` | Bottom margin (px) *(Layout)*. |
| `use_metafields` | checkbox | default `False` | Use product metafields for bar values *(Product Metafields)*. When enabled, bar percentages are pulled from product metafields instead of the manual settings. Falls back to manual values if a metafield is not set. |
| `metafield_namespace` | text | default `custom` | Metafield namespace *(Product Metafields)*. Found in Settings > Custom data > Products. Most metafields use "custom" as the namespace. |
| `bar1_metafield_key` | text | | Bar 1 - Metafield key *(Product Metafields)*. Enter the metafield key exactly as it appears in your metafield definition (e.g. true\_to\_size) |
| `bar2_metafield_key` | text | | Bar 2 - Metafield key *(Product Metafields)*. Enter the metafield key exactly as it appears in your metafield definition (e.g. length) |
| `bar3_metafield_key` | text | | Bar 3 - Metafield key *(Product Metafields)*. Enter the metafield key exactly as it appears in your metafield definition (e.g. stretch) |

Plus 13 appearance settings (colors, sizes, spacing).


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