> ## 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.

# Buying options and variant blocks

> Every block that controls how customers choose and buy: variant pickers, quantity breaks, bundles, subscriptions, and the add to cart button

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.

### Variant Picker

Block ID `pdp-simple-picker-block`.

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `hide_option_1` | checkbox | default `False` | Hide Option 1 *(Option 1)*. |
| `option_1_display_type` | select | `auto`, `variant_image`, `color_swatch`, `dropdown`, `image_dropdown`, `buttons`, `size_buttons` / default `auto` | Display Type *(Option 1)*. |
| `option_1_dropdown_fullwidth` | checkbox | default `True` | Full width *(Option 1)*. |
| `option_1_image_layout` | select | `inline`, `grid_2`, `grid_3`, `list` / default `inline` | Image layout *(Option 1)*. |
| `option_1_text_orientation` | select | `vertical`, `horizontal` / default `vertical` | Text Position *(Option 1)*. |
| `option_1_horizontal_text_align` | select | `left`, `center`, `right` / default `center` | Text Alignment *(Option 1)*. |
| `option_1_horizontal_style` | select | `simple`, `quantity_break` / default `simple` | List Style *(Option 1)*. |
| `option_1_list_inline` | checkbox | default `False` | Compact layout *(Option 1)*. Display list items inline with wrap instead of full-width rows. |
| `option_1_dynamic_images_variant_change` | checkbox | default `False` | Update images on variant change *(Option 1)*. Refresh list item images when the selected variant changes. |
| `hide_option_2` | checkbox | default `False` | Hide Option 2 *(Option 2)*. |
| `option_2_display_type` | select | `auto`, `variant_image`, `color_swatch`, `dropdown`, `image_dropdown`, `buttons`, `size_buttons` / default `auto` | Display Type *(Option 2)*. |
| `option_2_dropdown_fullwidth` | checkbox | default `True` | Full width *(Option 2)*. |
| `option_2_image_layout` | select | `inline`, `grid_2`, `grid_3`, `list` / default `inline` | Image layout *(Option 2)*. |
| `option_2_text_orientation` | select | `vertical`, `horizontal` / default `vertical` | Text Position *(Option 2)*. |
| `option_2_horizontal_text_align` | select | `left`, `center`, `right` / default `center` | Text Alignment *(Option 2)*. |
| `option_2_horizontal_style` | select | `simple`, `quantity_break` / default `simple` | List Style *(Option 2)*. |
| `option_2_list_inline` | checkbox | default `False` | Compact layout *(Option 2)*. Display list items inline with wrap instead of full-width rows. |
| `option_2_dynamic_images_variant_change` | checkbox | default `False` | Update images on variant change *(Option 2)*. Refresh list item images when the selected variant changes. |
| `hide_option_3` | checkbox | default `False` | Hide Option 3 *(Option 3)*. |
| `option_3_display_type` | select | `auto`, `variant_image`, `color_swatch`, `dropdown`, `image_dropdown`, `buttons`, `size_buttons` / default `auto` | Display Type *(Option 3)*. |
| `option_3_dropdown_fullwidth` | checkbox | default `True` | Full width *(Option 3)*. |
| `option_3_image_layout` | select | `inline`, `grid_2`, `grid_3`, `list` / default `inline` | Image layout *(Option 3)*. |
| `option_3_text_orientation` | select | `vertical`, `horizontal` / default `vertical` | Text Position *(Option 3)*. |
| `option_3_horizontal_text_align` | select | `left`, `center`, `right` / default `center` | Text Alignment *(Option 3)*. |
| `option_3_horizontal_style` | select | `simple`, `quantity_break` / default `simple` | List Style *(Option 3)*. |
| `option_3_list_inline` | checkbox | default `False` | Compact layout *(Option 3)*. Display list items inline with wrap instead of full-width rows. |
| `option_3_dynamic_images_variant_change` | checkbox | default `False` | Update images on variant change *(Option 3)*. Refresh list item images when the selected variant changes. |
| `hide_option_4` | checkbox | default `False` | Hide Option 4 *(Option 4)*. |
| `option_4_display_type` | select | `auto`, `variant_image`, `color_swatch`, `dropdown`, `image_dropdown`, `buttons`, `size_buttons` / default `auto` | Display Type *(Option 4)*. |
| `option_4_dropdown_fullwidth` | checkbox | default `True` | Full width *(Option 4)*. |
| `option_4_image_layout` | select | `inline`, `grid_2`, `grid_3`, `list` / default `inline` | Image layout *(Option 4)*. |
| `option_4_text_orientation` | select | `vertical`, `horizontal` / default `vertical` | Text Position *(Option 4)*. |
| `option_4_horizontal_text_align` | select | `left`, `center`, `right` / default `center` | Text Alignment *(Option 4)*. |
| `option_4_horizontal_style` | select | `simple`, `quantity_break` / default `simple` | List Style *(Option 4)*. |
| `option_4_list_inline` | checkbox | default `False` | Compact layout *(Option 4)*. Display list items inline with wrap instead of full-width rows. |
| `option_4_dynamic_images_variant_change` | checkbox | default `False` | Update images on variant change *(Option 4)*. Refresh list item images when the selected variant changes. |
| `first_variant_auto_selected` | checkbox | default `True` | Auto-select first variant on load *(Behavior)*. |
| `enable_size_preset` | checkbox | default `True` | Enable size abbreviations *(Behavior)*. Shows abbreviated size labels (S, M, L, XL) when Auto mode detects a size option. |
| `enable_color_swatches` | checkbox | default `True` | Enable color swatches *(Behavior)*. Shows color circles instead of buttons when Auto mode detects a color option. |
| `show_labels` | checkbox | default `True` | Show option labels *(Labels)*. |
| `show_selected_value_next_to_label` | checkbox | default `True` | Show selected value next to label *(Labels)*. e.g. 'Color: Red' |
| `color_swatches_style_mode` | select | `preset`, `custom` / default `preset` | Style *(Color Swatches)*. Preset uses theme defaults. Switch to Custom to fine-tune this picker type. |
| `custom_color_mappings` | textarea | default \`red=#FF0000 | |
| blue=#0000FF | | | |
| green=#00FF00 | | | |
| yellow=#FFFF00 | | | |
| black=#000000 | | | |
| white=#FFFFFF\` | Color mappings *(Color Swatches)*. Map color names to hex codes, one per line. Format: name=#HEXCODE | | |
| `use_theme_colors` | checkbox | default `False` | Use theme colors *(Colors & Style)*. Use global theme accent colors instead of the custom colors below. |
| `selected_option_inner_shadow` | checkbox | default `False` | Inner shadow on selected swatch *(Colors & Style)*. |
| `dropdown_style_mode` | select | `preset`, `custom` / default `preset` | Style *(Dropdown)*. Preset uses theme defaults. Switch to Custom to fine-tune this picker type. |
| `size_buttons_style_mode` | select | `preset`, `custom` / default `preset` | Style *(Size Buttons)*. Preset uses theme defaults. Switch to Custom to fine-tune this picker type. |
| `option_buttons_style_mode` | select | `preset`, `custom` / default `preset` | Style *(Option Buttons)*. Preset uses theme defaults. Switch to Custom to fine-tune this picker type. |
| `variant_images_style_mode` | select | `preset`, `custom` / default `preset` | Style *(Variant Images)*. Preset uses theme defaults. Switch to Custom to fine-tune this picker type. |
| `show_variant_images` | checkbox | default `True` | Show variant images on swatches *(Variant Images)*. Overlays the variant's product image on color swatches. |
| `variant_images_option_position` | select | `auto`, `1`, `2`, `3` / default `auto` | Apply to option *(Variant Images)*. |
| `variant_image_size_mode` | select | `square`, `custom` / default `square` | Image size *(Variant Images)*. |
| `show_variant_shadows` | checkbox | default `False` | Show drop shadows *(Variant Images)*. |
| `display_variant_images_on_select` | checkbox | default `False` | Filter gallery on variant change *(Variant Gallery)*. Reorders/filters the product image gallery when a variant is selected. |
| `variant_gallery_type` | select | `variant_images_first`, `variant_images_only` / default `variant_images_first` | Gallery filter mode *(Variant Gallery)*. |
| `horizontal_image_fade` | checkbox | default `False` | Fade image into text *(Grid & Horizontal Layout)*. |
| `horizontal_image_fullwidth` | checkbox | default `False` | Full-width background image *(Grid & Horizontal Layout)*. Stretches the variant image as a full background behind each row. |
| `hide_fullwidth_text` | checkbox | default `False` | Hide variant name on image *(Grid & Horizontal Layout)*. |
| `fullwidth_text_position` | select | `inside`, `below` / default `inside` | Text position *(Grid & Horizontal Layout)*. |
| `show_fullwidth_save_badge` | checkbox | default `False` | Show save badge *(Full-Width Image Text)*. |
| `save_badge_prefix` | text | default `Save {savings_amount}` | Save badge text *(Full-Width Image Text)*. Use \{savings\_percent} for percentage (e.g. '20%') and \{savings\_amount} for dollar savings (e.g. '\$10'). |
| `show_variant_price` | checkbox | default `False` | Show variant price *(Variant Price)*. |
| `show_compare_at_price` | checkbox | default `False` | Show compare-at price *(Variant Price)*. |
| `price_display_position` | select | `inside`, `below` / default `inside` | Price position *(Variant Price)*. |
| `list_style_style_mode` | select | `preset`, `custom` / default `preset` | Style *(List Style)*. Preset uses theme defaults. Switch to Custom to fine-tune this picker type. |
| `list_show_radio_button` | checkbox | default `False` | Show radio buttons *(List Style)*. |
| `multiply_price_by_quantity` | checkbox | default `True` | Multiply price by quantity *(List Style)*. List prices reflect the quantity set in the add-to-cart form. |
| `apply_selected_subscription_discount` | checkbox | default `True` | Apply subscription discount to prices *(List Style)*. List prices reflect the active selling plan discount. |

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

### Variant Cards

Block ID `pdp-variant-cards-block`.

Child blocks: `pdp-variant-card-block`

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `show_variant_images` | checkbox | default `True` | Show Variant Images *(Display)*. Display product/variant images in the cards. |
| `show_price` | checkbox | default `True` | Show Price *(Display)*. Display variant prices on the cards. |
| `show_compare_price` | checkbox | default `True` | Show Compare at Price *(Display)*. Display crossed-out original prices when available. |
| `show_variant_description` | checkbox | default `False` | Show Descriptions *(Display)*. Show a description on each card. Set per-card text on each Variant Card child block. |
| `multiply_price_by_quantity` | checkbox | default `True` | Multiply price by quantity *(Pricing)*. When on, variant card prices reflect the quantity set in the form (e.g. from Quantity Bundle block). |
| `apply_selected_subscription_discount` | checkbox | default `True` | Apply selected subscription discount *(Pricing)*. When on, variant card prices reflect the selected subscription/selling plan discount when applicable. |
| `card_sizing_mode` | select | `preset`, `custom` / default `preset` | Card Sizing *(Card Styling)*. Preset uses sensible defaults. Custom lets you control card dimensions. |
| `image_padding_style` | select | `full_width`, `with_padding` / default `full_width` | Image Padding Style *(Card Styling)*. Choose whether the image fills the full card width or has padding around it. |
| `typography_sizing_mode` | select | `preset`, `custom` / default `preset` | Typography Sizing *(Typography Sizing)*. Preset uses sensible defaults. Custom lets you control all font sizes. |
| `badge_sizing_mode` | select | `preset`, `custom` / default `preset` | Badge Sizing *(Badge Styling)*. Preset uses sensible defaults. Custom lets you control badge dimensions and position. |
| `save_badge_below_price` | checkbox | default `False` | Show save badge below price *(Badge Styling)*. Position the save badge below the price instead of next to the title. |
| `enable_hover_effects` | checkbox | default `True` | Enable Hover Effects *(Advanced)*. Add smooth transitions and hover animations. |
| `show_sold_out_overlay` | checkbox | default `True` | Show Sold Out Overlay *(Advanced)*. Gray out and overlay sold out variants. |

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

### Quantity Selector

Block ID `pdp-qty-selector-block`.

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `qty_style` | select | `stepper`, `dropdown` / default `stepper` | Style *(Style)*. |
| `dropdown_max` | range | default `10` | Dropdown max quantity *(Style)*. |
| `margin_top` | range | default `0` | Margin top (px) *(Spacing)*. |
| `margin_bottom` | range | default `12` | Margin bottom (px) *(Spacing)*. |

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

### Quantity Break

Block ID `pdp-quantity-break-block`.

Child blocks: `pdp-qb-option-block`

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `preselected_option` | select | `first_visible`, `option_1`, `option_2`, `option_3` / default `first_visible` | Pre-selected option. |
| `show_radio_buttons` | checkbox | default `True` | Show radio buttons. |
| `hide_images` | checkbox | default `False` | Hide option images. |
| `show_pricing` | checkbox | default `True` | Show pricing. Hide the price and compare-at price shown on each option. |
| `show_save_badge` | checkbox | default `True` | Show save badge *(Save Badge)*. Shows a badge (e.g. 'Save \$10') next to the title when savings exist. |
| `save_badge_text` | text | default `SAVE {savings_amount}` | Badge text *(Save Badge)*. Use \{savings\_percent} for percentage (e.g. '20%') and \{savings\_amount} for dollar savings (e.g. '\$10'). |
| `enable_badge_shine` | checkbox | default `True` | Enable badge shine effect *(Save Badge)*. |
| `variant_layout` | select | `dropdown`, `swatches`, `text` / default `dropdown` | Display style *(Variant Selection)*. |
| `variant_visual_option` | select | `auto`, `1`, `2`, `3`, `none` / default `auto` | Visual option *(Variant Selection)*. Which option position shows thumbnails or swatches. 'Auto detect' uses the option with 2+ distinct variant images. |
| `enable_variant_selection` | checkbox | default `False` | Show variant selectors *(Variant Selection)*. Show variant option dropdowns for each item row across all tiers. |
| `update_gallery_on_variant_change` | checkbox | default `False` | Update gallery on variant change *(Variant Selection)*. Swap the main product image to the selected variant's image when a variant option changes. |
| `hide_product_title_in_variants` | checkbox | default `False` | Hide product title in labels *(Variant Selection)*. |
| `card_select_animation` | select | `scale`, `none` / default `none` | Card Selection Animation *(Option Card Colors)*. |
| `enable_individual_borders` | checkbox | default `False` | Individual border widths *(Option Card Colors)*. Set a different border width per side, e.g. 3px bottom and right for a 3D effect. |
| `selected_border_style` | select | `solid`, `dashed`, `dotted` / default `solid` | Selected border style *(Option Card Colors)*. |
| `unselected_border_style` | select | `solid`, `dashed`, `dotted` / default `solid` | Unselected border style *(Option Card Colors)*. |
| `enable_selected_gradient` | checkbox | default `False` | Enable gradient on selected option *(Selected Option Gradient)*. |
| `selected_gradient_direction` | select | `to right`, `to left`, `to bottom`, `to top`, `to bottom right`, `to bottom left` / default `to right` | Direction *(Selected Option Gradient)*. |
| `show_quantity_circle` | checkbox | default `True` | Show quantity circle *(Quantity Circle)*. Shows the numbered circle (#1, #2, ...) next to each variant row. |
| `typography_sizing_mode` | select | `preset`, `custom` / default `preset` | Sizing *(Typography Sizing)*. Preset uses the built-in sizes. Switch to Custom to fine-tune the size controls below. |
| `spacing_mode` | select | `preset`, `custom` / default `preset` | Spacing *(Spacing)*. Preset uses the built-in spacing. Switch to Custom to fine-tune the spacing controls below. |

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

<Warning>
  **Custom pricing is display only.** `option_1_custom_price_amount` and friends change what the
  tier shows, not what Shopify charges. A tier advertising a bundle price needs a matching automatic
  discount or the cart will charge full price. See
  [Quantity break pricing and the cart](/guides/quantity-break-pricing).
</Warning>

<Warning>
  **Free gift badges need more than their checkbox.** `option_1_show_free_gift` through
  `option_4_show_free_gift` render nothing unless the product has real variants, **Show variant
  selectors** is on, and the tier quantity is above 1. All three must hold. See
  [Free gifts](/guides/free-gifts#free-gift-badges-on-quantity-break-tiers).
</Warning>

<Note>
  **Turning quantity break options into dropdowns.** The dropdown control is hidden until variant
  selection is switched on, which is why it looks like the setting does not exist.

  1. Open the **Quantity Break** block in the theme editor.
  2. Under **Variant Selection**, turn on **Show variant selectors**.
  3. **Display style** now appears. Set it to **Image dropdown**.

  `variant_layout` also offers **Swatches** and **Text only**. Use **Visual option** to choose which
  option position (1, 2 or 3) renders as thumbnails or swatches, or leave it on **Auto detect**.
</Note>

<Tip>
  **Multiple option selections inside a bundle.** Each tier row gets its own set of option selectors
  once **Show variant selectors** is on, so a customer buying 3 can pick a different colour or size
  for each one. Turn on **Update gallery on variant change** if you want the main image to follow
  their selection.
</Tip>

### Quantity Offers

Block ID `pdp-quantity-offers-block`.

Child blocks: `pdp-quantity-bundle-block-offer-block`

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `layout_type` | select | `horizontal`, `grid_2x2` / default `horizontal` | Layout Type *(Layout Settings)*. Horizontal displays cards in a row. Grid displays cards in a grid. |
| `content_alignment` | select | `left`, `center`, `right` / default `center` | Content Alignment *(Layout Settings)*. |
| `image_placement` | select | `before`, `after` / default `before` | Image Placement *(Layout Settings)*. |
| `price_layout` | select | `inline`, `stacked` / default `inline` | Price Layout *(Layout Settings)*. Inline shows prices side by side. Stacked places compare price below current price. |
| `per_item_price_position` | select | `inline`, `below` / default `below` | Per-Item Price Position *(Layout Settings)*. |
| `card_select_animation` | select | `raise`, `scale`, `none` / default `none` | Card Selection Animation *(Layout Settings)*. |
| `apply_selected_subscription_discount` | checkbox | default `True` | Apply selected subscription discount *(Subscription)*. |
| `card_sizing_mode` | select | `preset`, `custom` / default `preset` | Card Sizing *(Card Styling)*. Preset uses sensible defaults. Custom lets you control card dimensions. |
| `selected_card_inner_shadow` | checkbox | default `False` | Enable Selected Card Inner Shadow *(Custom Card Styling)*. |
| `customize_mobile` | checkbox | default `False` | Customize Mobile *(Custom Card Styling)*. Override card padding on mobile instead of using scaled defaults. |
| `typography_sizing_mode` | select | `preset`, `custom` / default `preset` | Typography Sizing *(Typography Sizing)*. Preset uses sensible defaults. Custom lets you control all font sizes. |
| `spacing_mode` | select | `preset`, `custom` / default `preset` | Spacing *(Spacing)*. Preset uses no extra margin. Custom lets you control top and bottom margin. |

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

### Bundle & Save

Block ID `pdp-bundle-and-save-block`.

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `product_list` | product\_list | | Product List *(Content Settings)*. Select the products to display in the bundle and save block |
| `title` | text | default `Bundle and Save` | Title *(Content Settings)*. |
| `show_header` | checkbox | default `True` | Show Header *(Header)*. |
| `subtitle` | text | | Subtitle *(Header)*. |
| `underline_style` | select | `none`, `solid`, `swipe`, `wave`, `scribble`, `circle`, `hook`, `highlight` / default `none` | Title Underline Style *(Header)*. |
| `text_alignment` | select | `left`, `center`, `right` / default `left` | Text Alignment *(Header)*. |
| `show_header_images` | checkbox | default `False` | Show Header Images *(Header)*. |
| `header_images_position` | select | `header`, `footer` / default `header` | Header Images Position *(Header)*. |
| `show_background` | checkbox | default `False` | Show Background *(Layout Settings)*. |
| `show_border` | checkbox | default `False` | Show Border *(Layout Settings)*. |
| `show_checkboxes` | checkbox | default `True` | Show Checkboxes *(Product Display Settings)*. |
| `alternate_row_colors` | checkbox | default `False` | Alternate Row Colors *(Product Display Settings)*. |
| `show_plus_separator` | checkbox | default `False` | Show Plus Separator *(Product Display Settings)*. |
| `plus_separator_alignment` | select | `left`, `center` / default `left` | Plus Separator Alignment *(Product Display Settings)*. |
| `show_variant_selector` | checkbox | default `True` | Show Variant Selector *(Product Display Settings)*. |
| `show_item_save_badges` | checkbox | default `True` | Show Item Save Badges *(Product Display Settings)*. |
| `save_badge_text` | text | default `SAVE &#123;savings_amount&#125;` | Save Badge Text *(Product Display Settings)*. Use \{savings\_percent} for percentage (e.g. '20%') and \{savings\_amount} for dollar savings (e.g. '\$10'). |
| `show_summary` | checkbox | default `True` | Show Summary *(Summary Settings)*. |
| `show_footer_border` | checkbox | default `False` | Show Footer Border *(Summary Settings)*. |
| `items_selected_text` | text | default `items selected` | Items Selected Text *(Summary Settings)*. |
| `show_fixed_bundle_text` | checkbox | default `False` | Show Fixed Bundle Text *(Summary Settings)*. |
| `fixed_bundle_text` | text | default `Bundle includes all items` | Fixed Bundle Text *(Summary Settings)*. |
| `use_toggle_switch` | checkbox | default `False` | Use Toggle Switch *(Button Settings)*. |
| `button_text` | text | default `Add Bundle to Cart` | Button Text *(Button Settings)*. |
| `show_price_in_button` | checkbox | default `False` | Show Price in Button *(Button Settings)*. |
| `button_icon` | select | `none`, `cart`, `bag`, `arrow`, `custom` / default `none` | Button Icon *(Button Icon)*. |
| `icon_position` | select | `left`, `right` / default `left` | Icon Position *(Button Icon)*. |
| `custom_icon` | html | | Custom Icon SVG *(Button Icon)*. Single-color SVG — inherits button text color. |
| `loading_indicator` | select | `spinner`, `text` / default `spinner` | Loading Indicator Style *(Loading Indicator)*. Spinner shows an animated ring. Text slides in using a vertical carousel animation. |
| `loading_text` | text | default `Adding…` | Loading Text *(Loading Indicator)*. Shown while the bundle is being added to cart. |
| `loading_add_text` | text | default `ADDING` | Loading Add Text *(Toggle Switch Settings)*. |
| `loading_remove_text` | text | default `REMOVING` | Loading Remove Text *(Toggle Switch Settings)*. |
| `toggle_on_text` | text | default `Added!` | Toggle On Text *(Toggle Switch Settings)*. |
| `toggle_off_text` | text | default `Removed` | Toggle Off Text *(Toggle Switch Settings)*. |
| `discount_code` | text | | Auto-apply Discount Code *(Discount Code Settings)*. Enter a discount code to automatically apply when bundle items are added to cart (leave empty to disable) |
| `typography_sizing_mode` | select | `preset`, `custom` / default `preset` | Typography sizing *(Typography Sizing)*. Preset uses theme defaults. Switch to Custom to fine-tune font sizes. |
| `spacing_mode` | select | `preset`, `custom` / default `preset` | Spacing & margins *(Spacing)*. Preset uses theme defaults. Switch to Custom to fine-tune margins, padding, and row spacing. |

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

### Subscribe & Save

Block ID `pdp-subscribe-save-block`.

Child blocks: `pdp-subscribe-benefit`

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `layout_mode` | select | `toggle`, `selector` / default `toggle` | Layout Mode *(Layout & Sizing)*. Toggle shows a switch to enable subscription. Selector shows two clickable cards for One-Time Purchase and Subscribe & Save. |
| `preselect_option` | select | `onetime`, `subscribe` / default `subscribe` | Preselect Option *(Layout & Sizing)*. |
| `onetime_title` | text | default `One-Time Purchase` | One-Time Purchase Title *(Layout & Sizing)*. |
| `selector_benefits_always_open` | checkbox | default `False` | Always Show Benefits *(Layout & Sizing)*. Keep the subscribe card benefits expanded even when one-time purchase is selected |
| `selector_show_discount_badge` | checkbox | default `False` | Show Discount Badge Instead of Price *(Layout & Sizing)*. Replace the subscribe price with a discount badge (e.g. '20% OFF'). Dynamically calculated from the selling plan. |
| `selector_discount_badge_text` | text | | Discount Badge Text (Static) *(Layout & Sizing)*. Leave blank to auto-calculate from selling plan (e.g. '20% OFF'). Set a value to use static text instead. |
| `subscribe_mode` | select | `custom`, `dynamic` / default `custom` | Configuration Mode *(Subscribe & Save Option)*. Choose 'Custom' to manually configure all settings, or 'Dynamic' to automatically use product selling plans |
| `show_benefits_dynamic` | checkbox | default `False` | Show benefits in dynamic mode *(Subscribe & Save Option)*. Display bonus items and free gifts inside each dynamic subscription card |
| `show_single_frequency_as_subtitle` | checkbox | default `True` | Show single delivery option as subtitle *(Subscribe & Save Option)*. When a plan has only one delivery frequency, show it as subtitle text instead of a dropdown. |
| `subscribe_title` | text | default `Subscribe & Save` | Title *(Dynamic pricing behavior)*. |
| `subscribe_title_subtitle` | richtext | default `&lt;p&gt;No contract, cancel with ease.&lt;/p&gt;` | Title Subtitle *(Dynamic pricing behavior)*. |
| `subscribe_subtitle` | text | default `Billed $218.00 USD every 12 weeks` | Subtitle *(Dynamic pricing behavior)*. |
| `subscribe_save_badge_text` | text | default `SAVE 35%` | Save badge text *(Dynamic pricing behavior)*. Static text for the subscription save badge (e.g. 'SAVE 35%'). Leave blank to hide. |
| `subscribe_quantity` | range | default `3` | Quantity *(Dynamic pricing behavior)*. |
| `enable_frequency_dropdown` | checkbox | default `False` | Enable Delivery Frequency Dropdown *(Dynamic pricing behavior)*. |
| `frequency_label` | text | default `Delivery every:` | Frequency Label *(Dynamic pricing behavior)*. Label displayed before the dropdown. |
| `frequency_options` | textarea | default \`2 weeks | |
| 4 weeks | | | |
| 6 weeks | | | |
| 8 weeks\` | Frequency Options *(Dynamic pricing behavior)*. Enter one option per line. First option will be selected by default. | | |
| `multiply_values_by_quantity` | checkbox | default `True` | Multiply values by quantity *(Dynamic pricing behavior)*. |
| `show_subscribe_price` | checkbox | default `True` | Show Subscribe Price *(Custom Subscribe Pricing)*. |
| `subscribe_price_text` | text | default `$72.8/mo` | Current Price *(Custom Subscribe Pricing)*. |
| `subscribe_compare_price_text` | text | default `$112` | Compare Price *(Custom Subscribe Pricing)*. |
| `subscribe_per_serving_text` | text | default `$2.42 USD / SERVING` | Per Serving Text *(Custom Subscribe Pricing)*. |
| `subscribe_selling_plan_id` | text | | Selling Plan ID *(Custom Subscribe Pricing)*. Required: Enter the selling plan ID from your subscription app |
| `benefits_layout` | select | `single`, `two_column`, `flex_row` / default `single` | Benefits Layout *(Subscribe Benefits List)*. Choose how to display the benefits list |
| `number_of_free_gifts` | range | default `0` | Number of Free Gifts *(Subscribe Free Gifts)*. |
| `subscribe_gift_1_image` | image\_picker | | Gift 1 Image *(Subscribe Free Gifts)*. |
| `subscribe_gift_1_text` | text | | Gift 1 Name *(Subscribe Free Gifts)*. |
| `subscribe_gift_1_qty` | text | default `1x` | Gift 1 Qty *(Subscribe Free Gifts)*. |
| `subscribe_gift_1_price` | text | default `FREE` | Gift 1 Price *(Subscribe Free Gifts)*. |
| `subscribe_gift_1_compare_price` | text | default `$20.00` | Gift 1 Compare Price *(Subscribe Free Gifts)*. |
| `subscribe_gift_2_image` | image\_picker | | Gift 2 Image *(Subscribe Free Gifts)*. |
| `subscribe_gift_2_text` | text | | Gift 2 Name *(Subscribe Free Gifts)*. |
| `subscribe_gift_2_qty` | text | default `1x` | Gift 2 Qty *(Subscribe Free Gifts)*. |
| `subscribe_gift_2_price` | text | default `FREE` | Gift 2 Price *(Subscribe Free Gifts)*. |
| `subscribe_gift_2_compare_price` | text | default `$20.00` | Gift 2 Compare Price *(Subscribe Free Gifts)*. |
| `subscribe_gift_3_image` | image\_picker | | Gift 3 Image *(Subscribe Free Gifts)*. |
| `subscribe_gift_3_text` | text | | Gift 3 Name *(Subscribe Free Gifts)*. |
| `subscribe_gift_3_qty` | text | default `1x` | Gift 3 Qty *(Subscribe Free Gifts)*. |
| `subscribe_gift_3_price` | text | default `FREE` | Gift 3 Price *(Subscribe Free Gifts)*. |
| `subscribe_gift_3_compare_price` | text | default `$20.00` | Gift 3 Compare Price *(Subscribe Free Gifts)*. |
| `subscribe_gift_4_image` | image\_picker | | Gift 4 Image *(Subscribe Free Gifts)*. |
| `subscribe_gift_4_text` | text | | Gift 4 Name *(Subscribe Free Gifts)*. |
| `subscribe_gift_4_qty` | text | default `1x` | Gift 4 Qty *(Subscribe Free Gifts)*. |
| `subscribe_gift_4_price` | text | default `FREE` | Gift 4 Price *(Subscribe Free Gifts)*. |
| `subscribe_gift_4_compare_price` | text | default `$20.00` | Gift 4 Compare Price *(Subscribe Free Gifts)*. |
| `subscribe_gift_5_image` | image\_picker | | Gift 5 Image *(Subscribe Free Gifts)*. |
| `subscribe_gift_5_text` | text | | Gift 5 Name *(Subscribe Free Gifts)*. |
| `subscribe_gift_5_qty` | text | default `1x` | Gift 5 Qty *(Subscribe Free Gifts)*. |
| `subscribe_gift_5_price` | text | default `FREE` | Gift 5 Price *(Subscribe Free Gifts)*. |
| `subscribe_gift_5_compare_price` | text | default `$20.00` | Gift 5 Compare Price *(Subscribe Free Gifts)*. |
| `toggle_style` | select | `toggle`, `checkbox` / default `toggle` | Toggle Style *(Toggle Switch Styling)*. Choose between a sliding toggle switch or a checkbox |
| `checkbox_border_style` | select | `solid`, `dashed`, `dotted` / default `solid` | Checkbox Border Style (Unchecked) *(Toggle Switch Styling)*. |
| `checkbox_checked_border_style` | select | `solid`, `dashed`, `dotted` / default `solid` | Checkbox Border Style (Checked) *(Toggle Switch Styling)*. |
| `border_style_unselected` | select | `solid`, `dashed`, `dotted` / default `solid` | Border Style (Unselected) *(Border & Corners)*. |
| `border_style_selected` | select | `solid`, `dashed`, `dotted` / default `solid` | Border Style (Selected) *(Border & Corners)*. |
| `enable_top_row_border` | checkbox | default `False` | Enable Divider *(Divider)*. |
| `show_save_badge` | checkbox | default `False` | Show Save Badge *(Save Badge (Next to Title))*. Display a save badge next to the option title |
| `gift_container_border_style` | select | `dashed`, `solid` / default `dashed` | Gift Container Border Style *(Gift/Bonus Styling)*. |
| `typography_sizing_mode` | select | `preset`, `custom` / default `preset` | Text sizing *(Typography Sizing)*. Preset uses recommended text sizes. Switch to Custom to set your own font sizes. |
| `colors_mode` | select | `preset`, `custom` / default `preset` | Colors *(Colors)*. Preset uses the recommended color palette. Switch to Custom to set your own colors. |
| `spacing_mode` | select | `preset`, `custom` / default `preset` | Spacing *(Spacing)*. Preset uses recommended spacing. Switch to Custom to set your own widths, margins, padding and gaps. |

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

### Add to Cart Button

Block ID `pdp-add-to-cart-block`.

| Setting | Type | Options / default | What it controls |
| - | - | - | - |
| `show_fast_payment` | checkbox | default `False` | Show Dynamic Checkout *(Dynamic Checkout)*. Displays accelerated payment buttons (Apple Pay, Google Pay, Shop Pay, etc.) when available. |
| `button_behavior` | select | `add_to_cart`, `skip_to_checkout` / default `add_to_cart` | Button Behavior *(Button Text & Behavior)*. |
| `button_text_override` | text | | Custom Button Text *(Button Text & Behavior)*. Replaces the default 'Add to Cart' text. Leave empty to use the default. |
| `show_price_in_button` | checkbox | default `True` | Show Price in Button *(Price in Button)*. |
| `price_style` | select | `current`, `pill` / default `current` | Price Style *(Price in Button)*. |
| `show_compare_price` | checkbox | default `False` | Show Compare At Price *(Price in Button)*. |
| `multiply_values_by_quantity` | checkbox | default `True` | Multiply Values by Quantity *(Price in Button)*. |
| `apply_selected_subscription_discount` | checkbox | default `True` | Apply Selected Subscription Discount *(Price in Button)*. |
| `loading_indicator` | select | `spinner`, `text` / default `spinner` | Loading Indicator Style *(Loading Indicator)*. Spinner shows an animated ring. Text slides in using a vertical carousel animation. |
| `loading_text` | text | default `Adding…` | Loading Text *(Loading Indicator)*. Shown while the item is being added to cart. The current button text slides up and away as this slides up and in. |
| `button_icon` | select | `none`, `cart`, `bag`, `arrow`, `custom` / default `none` | Button Icon *(Button Icon)*. |
| `icon_position` | select | `left`, `right` / default `left` | Icon Position *(Button Icon)*. |
| `custom_icon` | html | | Custom Icon SVG *(Button Icon)*. Single-color SVG — inherits button text color. |
| `enable_custom_style` | checkbox | default `False` | Override Global Button Styling *(Button Style)*. When off, the button inherits your global button settings (colors, radius, padding, font size). Turn on to customize this button individually. |
| `button_font_family` | select | `body`, `heading`, `accent` / default `body` | Font Family *(Button Style)*. |

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


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