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/