PPS BOGO Deals: settings reference

Updated November 10, 2026

Set the buy and reward quantities in WooCommerce > BOGO Deals before enabling the deal. Pro features require the active Free parent and paid entitlement.

Release in preparation. This reference is not confirmation of download or Pro purchase availability.

Buy X get Y counts eligible units in the cart. In Free, the reward is more of the same product at 100% off. The shopper must have the reward units in the cart; this is not Free auto-add.

Where to configure it

WooCommerce > BOGO Deals. The menu and save handler require manage_woocommerce. Use Save Changes after editing.

Settings are saved in pps_bogo_settings. Initial form values and unsaved runtime values can differ; both appear below. Product trigger overrides are separate WooCommerce product fields. There is no rule CPT/repeater or additional Design system.

The deal

Field Initial form / unsaved runtime Allowed input and save fallback Access Effect
Enable (enabled) Form: blank; runtime: unchecked On/off. Unchecked saves false. Free Turn on the buy X get Y engine.
Buy quantity (X) (buy_qty) 1 Number; min 1; UI step 1. Save casts to float with minimum 1; blank uses 1. Runtime requires an integer in 1-1000000. Free Paid units per deal. Invalid runtime quantities prevent the deal rather than guessing a quantity.
Get quantity (Y) (get_qty) 1 Same save and runtime quantity limits as X. Free Reward units per deal; per-product quantities apply when that product's override is enabled.
Which products trigger the deal (buy_target) any any = Any product; specific_products = Specific product IDs; categories = Categories (Pro). Invalid input uses any. Saving without Pro resets a paid category choice to any. Free field; paid choice categories needs Pro Sets trigger scope. Review this choice before saving after paid denial, since the Free default is broader.
Trigger product IDs (buy_specific_products) blank Text; stripped of markup on save. Comma separated, for the specific products option. The per-product override on the product edit screen also makes a product a trigger. Free Comma separated, for the specific products option. The per-product override on the product edit screen also makes a product a trigger.
Trigger category IDs (buy_categories) blank Text; stripped of markup on save. Comma separated category IDs, for the categories option. Pro field; save skipped without Pro Comma separated category IDs, for the categories option.

The reward

Field Initial form / unsaved runtime Allowed input and save fallback Access Effect
What the customer gets (get_target) same same = More of the same product; specific_product = A different product (Pro). Invalid input uses same. Saving without Pro resets the paid choice to same. Free field; paid choice specific_product needs Pro With more of the same, buy 1 get 1 means the second unit already in the cart is the reward.
Reward product ID (get_product_id) 0 Number; min 0; UI step 1. Blank saves 0. Runtime requires a positive integer ID of a purchasable in-stock simple product or concrete variation. Pro field; save skipped without Pro Used for a different reward. A variable parent is not a selectable reward; a variation uses its stored parent and attributes.
Auto-add the reward (auto_add) Form: blank; runtime: unchecked On/off. Unchecked saves false. Pro field; save skipped without Pro For a different reward, inserts/reconciles a separate owned cart line after native WooCommerce acceptance. Off discounts eligible reward units already in the cart. It does not auto-add same-product units.
Reward discount (discount_type) free free = Free (100% off); percentage = Percentage off; fixed = Fixed amount off. Invalid input uses free. Pro field; save skipped without Pro Sets reward discount for this section. See the behavior notes for its conditions.
Discount value (discount_value) 0 Number; min 0; UI step 0.01. Blank saves 0. Runtime requires a finite nonnegative value; percentage caps at 100. Pro field; save skipped without Pro Percentage off each reward unit, or a fixed store-currency reduction per reward unit, never below zero. A malformed paid discount leaves the normal base price, not a free reward.

Offer box on the product page

Field Initial form / unsaved runtime Allowed input and save fallback Access Effect
Offer box (show_offer_box) Form: blank; runtime: checked On/off. Unchecked saves false. Free Show a small highlight box on trigger products.
Title (offer_title) Special offer: buy {x}, get {y} free Text; stripped of markup on save. {x} and {y} are replaced with the deal quantities. Free {x} and {y} are replaced with the deal quantities.
Description (offer_desc) blank Text; stripped of markup on save. Free Sets description for this section. See the behavior notes for its conditions.
Position (offer_position) woocommerce_single_product_summary woocommerce_single_product_summary = In the product summary; woocommerce_before_add_to_cart_form = Before the add to cart form; woocommerce_after_add_to_cart_form = After the add to cart form. Invalid input uses woocommerce_single_product_summary. Pro field; save skipped without Pro Sets position for this section. See the behavior notes for its conditions.
Background (box_bg_color) #F8FAFC Hex color (#RGB or #RRGGBB). Invalid/blank saves #F8FAFC. Free Sets background in this section; it does not change other plugin colors.
Border (box_border_color) #E2E8F0 Hex color (#RGB or #RRGGBB). Invalid/blank saves #E2E8F0. Free Sets border in this section; it does not change other plugin colors.
Title (box_title_color) #111827 Hex color (#RGB or #RRGGBB). Invalid/blank saves #111827. Free Sets title in this section; it does not change other plugin colors.
Description (box_desc_color) #4B5563 Hex color (#RGB or #RRGGBB). Invalid/blank saves #4B5563. Free Sets description in this section; it does not change other plugin colors.
Icon (box_icon_color) #3B82F6 Hex color (#RGB or #RRGGBB). Invalid/blank saves #3B82F6. Free Sets icon in this section; it does not change other plugin colors.

Notice bar

Field Initial form / unsaved runtime Allowed input and save fallback Access Effect
Notice bar (notice_enabled) Form: blank; runtime: unchecked On/off. Unchecked saves false. Free Show a promo strip on product pages.
Message (notice_message) Buy 1 get 1 free on select items! Text; stripped of markup on save. Free The historical literal default is rendered with current {x}/{y} quantities. Pro substitutes a discounted-reward default for partial discounts; merchant custom copy remains unchanged. Blank produces no strip.
Icon (notice_icon) gift gift = Gift; fire = Flame; lightning = Lightning; tag = Tag; star = Star; megaphone = Megaphone; none = No icon. Invalid input uses gift. Free Sets icon for this section. See the behavior notes for its conditions.
Position (notice_position) above_title above_title = Above the product title; below_price = Below the price; above_cart = Above the add to cart form. Invalid input uses above_title. Pro field; save skipped without Pro Sets position for this section. See the behavior notes for its conditions.
Alignment (notice_alignment) center left = Left; center = Center; right = Right. Invalid input uses center. Free Sets alignment for this section. See the behavior notes for its conditions.
Dismissible (notice_dismissible) Form: blank; runtime: checked On/off. Unchecked saves false. Free Show a close button; stays closed for the browser session.
On click (notice_click_action) none none = Nothing; scroll_to_cart = Scroll to the add to cart button; custom_url = Open a URL. Invalid input uses none. Free Sets on click for this section. See the behavior notes for its conditions.
URL (notice_custom_url) blank Text; stripped of markup on save. Free Sets url for this section. See the behavior notes for its conditions.
Show on (notice_display_on) entire_store entire_store = Every product; products = Specific product IDs; categories = Specific category IDs. Invalid input uses entire_store. Pro field; save skipped without Pro Narrows eligible trigger-product pages; it does not advertise deals on ineligible products. A selected products/categories mode with an empty ID list shows no strip.
Product IDs (notice_products) blank Text; stripped of markup on save. Pro field; save skipped without Pro Sets product ids for this section. See the behavior notes for its conditions.
Category IDs (notice_categories) blank Text; stripped of markup on save. Pro field; save skipped without Pro Sets category ids for this section. See the behavior notes for its conditions.
Background (notice_bg_color) #FEE2E2 Hex color (#RGB or #RRGGBB). Invalid/blank saves #FEE2E2. Free Sets background in this section; it does not change other plugin colors.
Text (notice_text_color) #991B1B Hex color (#RGB or #RRGGBB). Invalid/blank saves #991B1B. Free Sets text in this section; it does not change other plugin colors.
Icon (notice_icon_color) #DC2626 Hex color (#RGB or #RRGGBB). Invalid/blank saves #DC2626. Free Sets icon in this section; it does not change other plugin colors.
Close button (notice_close_color) #991B1B Hex color (#RGB or #RRGGBB). Invalid/blank saves #991B1B. Free Sets close button in this section; it does not change other plugin colors.

Additional product controls

Field Location Format and initial value Access Behavior
This product triggers the deal (_pps_bogo_override) Products > Edit product > Product data > Advanced checkbox, unchecked Free Enables this product as a trigger and uses its quantities.
Buy quantity (X) (_pps_bogo_buy_qty) Products > Edit product > Product data > Advanced integer, minimum 1; blank inherits Free Saved as an absolute integer, at least 1.
Get quantity (Y) (_pps_bogo_get_qty) Products > Edit product > Product data > Advanced integer, minimum 1; blank inherits Free Saved as an absolute integer, at least 1.

Behavior and edition boundaries

Category triggers, different rewards, auto-add, partial discounts, notice targeting/placements and scoped CSS are Pro-owned. Paid previews/saves and runtime recheck explicit entitlement; stored paid data or forced UI flags do not authorize them. Denial removes owned separate rewards while useful Free same-line free-unit behavior remains. A retained category mode has no Free category match before a fresh save, although an explicit Free product trigger override can qualify. Saving without Pro resets locked mixed choices to their Free defaults, including categories to any and a different reward to same; review scope before saving.

For same-product rewards, the shopper supplies all units. For cart quantity q, X paid and Y reward units, each full X+Y cycle earns Y rewards and any remaining units above X are rewards too. A 1+1 deal therefore needs two cart units for its first free unit. The unit price is blended across the line; no duplicate same-product gift is inserted. Known automatic gifts from other supported marker conventions, including Free Gift and Auto-Add lines, are excluded as triggers/rewards.

For a different reward, each trigger line earns floor(trigger quantity / X) times Y, internally bounded to 1000000 units per trigger. Auto-add uses exact product/variation identity and authoritative attributes. Paid reward lines remain separate. Final owned allocations are reserved in trigger-cart order before mutation; paid and foreign-gift quantities still count against stock. Each trigger's full allocation must fit or that allocation is rejected, rather than partially filled. All rejected lines and reductions are processed before any growth, with another stock check before insertion. Sold-individually and backorder rules still apply. No BOGO gift-added success notice is emitted, including on insertion failure.

Each totals pass restores only this plugin's prior price write before recomputing; a different subsequent external price is respected. Cloned price objects isolate cart lines. Changed quantities, reward identity, eligibility or paid approval reconcile owned rewards and restore applicable prices. This is not broad compatibility or concurrency proof for other pricing extensions.

Offer and notice output require an enabled, eligible trigger product. Without Pro, stale paid placements fall back to the Free positions instead of showing in the wrong paid hook. Use {x}/{y} in offer title/description. Default partial-discount copy says discounted reward units, not free; custom merchant wording is not rewritten and must describe the actual deal.

Custom CSS (Pro)

Field Initial value Format, save and effect Access
Scoped custom CSS (custom_css) Blank CSS declarations, not a separate design editor. Saved text is consumed only while entitled; the Pro sanitizer removes disallowed patterns/properties and wraps remaining declarations under .shopbooster-module-bogo. Not arbitrary CSS execution or a general security guarantee. Pro

Pro field access depends on the add-on and its licensing gate. Freemius account or license screens are separate from frontend rendering; opening an account page does not establish that a feature rendered.

Troubleshooting

If no discount appears, check trigger scope, whole-number X/Y and actual cart units. For a missing different reward, use a concrete eligible ID, check paid/foreign gift stock consumption, sold-individually limits and full-allocation cart order. Check the cart after native insertion failure; no success notice proves an add. Empty targeted notice lists show nothing. Verify custom copy separately when using a partial discount.

Disable or roll back safely

Record the current values before changing them. Clear Enable and save to stop new module output/actions. Revert one setting at a time. Deactivation is not an undo of cart changes, sent messages, created orders or saved records. Avoid uninstalling as a rollback, since uninstall may remove data. Back up the database before a data-changing rollback.

Services and data

The engine modifies WooCommerce cart prices and reward cart items. The notice close state is stored for the browser session.

Account, licensing and updater traffic must be reviewed separately. This reference does not claim that all data stays local or that a service connection has been tested.

Related documentation

Setup: https://propluginstack.com/docs/bogo-deals-setup-reference/

Changelog: https://propluginstack.com/changelog/bogo-deals-source-changelog/