GoalPrevail Sales Pop – User Guide

1. What this plugin does

GoalPrevail Sales Pop displays compact recent-order notifications in a selected corner of the storefront.

The plugin can retrieve recent paid WooCommerce orders automatically or build events from manually configured names, locations and products.

• Automatic WooCommerce source — retrieve up to 20 recent paid orders.
• Manual source — create rotating events from editable entry pools.
• Flexible message template — arrange the name, location and product placeholders.
• Four positions — choose any top or bottom corner.
• Timing controls — configure the first delay, interval and display duration.
• Content controls — choose whether to show a first name, relative time and dismiss button.
• Appearance settings — customize background, text, accent color and corner radius.
• Live preview — see changes while editing the settings.
• Reduced-motion support — respects the visitor’s browser preference.
• HPOS compatibility — uses WooCommerce order APIs instead of direct database queries.

WooCommerce is required for installation and supplies all events when the Automatic source is selected.

2. Requirements and installation

2.1 Requirements

• WordPress 6.0 or newer
• PHP 7.4 or newer
• WooCommerce installed and active
• Administrator access
• A modern browser with JavaScript enabled

2.2 Installation

1. Make sure WooCommerce is installed and active.
2. Upload the goalprevail-sales-pop folder to /wp-content/plugins/, or use Plugins → Add New → Upload Plugin.
3. Activate GoalPrevail Sales Pop.
4. Open GoalPrevail Plugins → Sales Pop.
5. Choose the data source and configure the popup.
6. Enable Sales Pop and click Save settings.
7. Open the storefront in a private or incognito window to test the result.

2.3 Default configuration

New installations begin with the following configuration:

• Sales Pop disabled
• Automatic — WooCommerce paid orders selected
• Bottom-left position
• First popup after 4 seconds
• New popup every 7–10 seconds
• Each popup visible for 5 seconds
• Continuous cycling enabled
• Template: {name} in {location} ordered {product}
• Customer first name hidden
• Relative time enabled
• Dismiss button enabled
• White background, dark text and red accent
• 12-pixel corner radius

3. Where to configure the plugin

All settings are available under:

GoalPrevail Plugins → Sales Pop

The direct administration URL is:

admin.php?page=goalprevail-sales-pop

The settings screen contains three tabs:

• General — enable the plugin, choose a source, select a position and configure timing.
• Content — edit the message, visibility options and manual entry pools.
• Appearance — customize popup colors and corner radius.

A live preview appears in the settings sidebar and refreshes while fields are edited.

Settings are saved through the standard WordPress Settings API. Click Save settings after making changes.

4. Quick-start configuration

4.1 Automatic WooCommerce setup

1. Open the General tab.
2. Keep Automatic — WooCommerce paid orders selected.
3. Choose the popup position and timing.
4. Open the Content tab.
5. Edit the message template if required.
6. Choose whether customer first names, relative time and the dismiss button should appear.
7. Open Appearance and choose the popup colors.
8. Return to General and enable Enable Sales Pop.
9. Click Save settings.
10. Test the storefront in a private browser window.

Automatic mode loads no popup assets when the store has no orders in a paid WooCommerce status.

4.2 Manual setup

1. Select Manual entries under Data source.
2. Open the Content tab.
3. Enter one name, location and product per line in the corresponding pools.
4. Customize the message template and relative-time range.
5. Enable Sales Pop and save the settings.

5. Choosing a data source

5.1 Automatic WooCommerce source

The automatic source queries WooCommerce through wc_get_orders(). It does not use direct SQL or assume that orders are stored as WordPress posts.

For each qualifying order, the plugin uses:

• The first purchased line item’s product name
• The billing country
• The actual payment time, or order creation time when a payment time is unavailable
• The billing first name only when the first-name setting is enabled

WooCommerce normally treats Processing and Completed orders as paid. Extensions may adjust the paid-status list through WooCommerce’s own filters.

The plugin skips an order when it has no usable line item, product name or date.

5.2 Manual source

The manual source selects one random value from each configured pool to compose an event.

If a pool is empty, the plugin uses its built-in sample list. Duplicate lines and blank lines are removed when settings are saved.

The manual time range controls the random “time ago” value. It does not affect timestamps pulled from WooCommerce.

6. Message and content settings

6.1 Message template

The default message is:

{name} in {location} ordered {product}

The following placeholders are supported:

Placeholders can be reordered or repeated. Text outside the placeholders is displayed as entered.

6.2 Show the customer’s billing first name

This setting is disabled by default. When disabled, {name} becomes “Someone”.

When Automatic is selected and the setting is enabled, the billing first name is included in the front-end event data.

6.3 Relative time

Enable Show a “x minutes ago” line to display how long ago an event occurred.

• Automatic events use the real order timestamp.
• Manual events use a random value between the configured minimum and maximum.
• Longer periods are automatically displayed in hours or days.

6.4 Dismiss button

Enable Show a dismiss (×) button to let visitors hide the current popup.

When continuous cycling is enabled, dismissing one popup does not prevent later events from appearing.

7. Manual data pools

Manual mode provides three newline-separated fields:

• Names
• Locations
• Products

Enter one value per line:

Emma
Liam
Olivia

Texas
London, UK
Toronto, CA

the Starter Bundle
a Pro License
the Deluxe Kit

When the popup is shown, one value is selected independently from each pool. The plugin attempts to avoid immediately repeating the same full combination.

• Blank lines are removed.
• Duplicate lines are removed.
• HTML is stripped when settings are saved.
• An empty field falls back to its built-in sample pool.

8. Position and timing

8.1 Position

The popup can appear in any of the following corners:

• Bottom left
• Bottom right
• Top left
• Top right

8.2 Timing controls

If a maximum value is saved below its matching minimum, the plugin raises the maximum to match the minimum.

8.3 Keep cycling

When enabled, a new event is scheduled after each popup appears. When disabled, the plugin displays one event after the initial delay and stops.

The cycle pauses while the browser tab is hidden. When the visitor returns, the next event is scheduled using a fresh random interval.

9. Appearance and live preview

9.1 Appearance controls

9.2 Live preview

The settings sidebar reuses the same card builder as the storefront. It updates when the message, source, data pools, position, visibility controls or appearance values change.

The sample event refreshes approximately every four seconds.

The preview is illustrative. Automatic storefront events are taken from qualifying WooCommerce orders after the settings are saved.

10. WooCommerce order handling

10.1 Paid-order query

The plugin requests a maximum of 20 orders with the following behavior:

• Only statuses returned by wc_get_is_paid_statuses()
• Newest orders first
• WooCommerce order objects returned through wc_get_orders()
• No direct query against wp_posts, post meta or HPOS tables

10.2 Event cache

Automatic events are cached for five minutes. Separate caches are used depending on whether first names are enabled.

The cache is cleared when WooCommerce reports:

• A new order
• An updated order
• An order-status change

This lets new paid orders become available without waiting for the full cache period.

10.3 No qualifying events

If Automatic is selected and no qualifying order events exist, the plugin does not enqueue its front-end stylesheet or script.

11. Front-end behavior and accessibility

• One fixed container is added to the selected corner.
• Only one event card is displayed at a time.
• Dynamic text is escaped before being inserted into the card.
• The card uses a polite live region so assistive technology can announce updates.
• The dismiss control has an accessible label.
• Animations are reduced when the browser reports prefers-reduced-motion: reduce.
• The popup width adapts to narrow screens.
• The cycle pauses when the document becomes hidden.

The front-end script creates the popup after the document is ready and does not require jQuery.

12. Performance and cache compatibility

• Assets load only when Sales Pop is enabled.
• Automatic mode loads no assets when no qualifying events exist.
• The WooCommerce query is limited to 20 orders.
• Automatic event results are cached for five minutes.
• No repeated AJAX request is made while the visitor remains on the page.
• No front-end request is sent to an external service.
• The popup is assembled locally in the browser.

12.1 Full-page caching

The event data is included in the generated page. A full-page cache can therefore continue serving the same event set until that cached page expires or is purged.

If rapid event turnover is important, configure the page cache to use an appropriate lifetime or purge strategy.

The plugin’s five-minute transient cache and a separate full-page cache are independent. Clearing one does not necessarily clear the other.

13. Privacy and security

13.1 Automatic event fields

Automatic event data can include:

• Billing first name, only when explicitly enabled
• Billing country
• First purchased product name
• Payment or creation timestamp

The plugin does not send the following order fields to the browser:

• Surname
• Email address
• Phone number
• Street address
• Postcode
• Order number or order ID

Store administrators are responsible for selecting settings appropriate for their store, customers and privacy obligations.

13.2 Administrative security

• The settings page requires the manage_options capability.
• Settings are saved through the WordPress Settings API with nonce protection.
• Submitted values are sanitized and restricted to recognized choices and ranges.
• Rendered administration output is escaped.
• The plugin uses WooCommerce CRUD and query APIs.
• No custom database tables or executable remote code are used.

13.3 WordPress.org administration request

When the shared GoalPrevail Plugins dashboard is opened, the plugin may query the official WordPress.org plugin API to list other plugins published by GoalPrevail.

• The request occurs only in the WordPress administration area.
• It is not made from customer-facing pages.
• The request includes the public author query and requested catalog fields.
• WordPress includes the WordPress version and site home URL in its standard HTTP user-agent.
• A successful response is cached for up to 24 hours.
• An empty or unsuccessful result may be cached for up to two hours.
• The dashboard may load returned plugin icons from WordPress.org’s plugin asset CDN.

14. Developer information

14.1 Front-end assets

14.2 PHP filters

14.3 Conditional display example

add_filter( 'gpsp_should_display', function ( $show, $settings ) {
    if ( is_cart() || is_checkout() ) {
        return false;
    }

    return $show;
}, 10, 2 );

14.4 Limit automatic events example

add_filter( 'gpsp_woocommerce_events', function ( $events, $settings ) {
    return array_slice( $events, 0, 10 );
}, 10, 2 );

14.5 Runtime configuration values

14.6 Stored data

No custom database tables, scheduled cron jobs, cookies or browser-storage values are created.

14.7 Shortcodes

The plugin does not provide a shortcode. The popup is added automatically when the plugin is enabled and events are available.

15. Troubleshooting

• No popup appears: Confirm that Enable Sales Pop is switched on and the settings have been saved.
• Automatic mode shows nothing: Confirm that WooCommerce is active and at least one order has a status WooCommerce considers paid.
• A new order is missing: Confirm that the order has reached a paid status, then clear any full-page or CDN cache.
• The wrong product appears: The plugin uses the first line item from each qualifying order.
• The name says Someone: Enable Show the customer’s billing first name and save the settings.
• The location is broad: Automatic mode intentionally uses the billing country rather than a street address, postcode or precise location.
• Manual values are not used: Confirm that Manual entries is selected and that each value is on a separate line.
• Sample manual values appear: An empty manual field falls back to its built-in sample pool.
• The timing seems different each time: The next event is scheduled randomly between the minimum and maximum interval.
• The popup appears only once: Enable Keep cycling.
• The popup returns after dismissal: Dismissal hides the current card; disable Keep cycling if only one event should appear.
• Changes do not appear: Clear the WordPress cache, server cache, CDN cache and browser cache.
• Colors revert after saving: Enter a complete six-digit hexadecimal color.
• The popup overlaps another widget: Choose another corner or adjust the other widget’s placement.
• The animation is reduced: The visitor’s browser may have reduced-motion preferences enabled.
• The cycle pauses: Popup scheduling intentionally pauses while the browser tab is hidden.

16. Uninstalling the plugin

1. Deactivate the plugin to stop storefront popups.
2. Delete it from the WordPress Plugins page when it is no longer required.
3. The uninstall process removes the gpsp_settings option.
4. Both WooCommerce event transients are removed.
5. The cached GoalPrevail WordPress.org catalog is removed.

On WordPress Multisite, uninstall cleanup is performed for every site on which the plugin may have stored settings or caches.

Deleting the plugin permanently removes its saved configuration. Record any manual entries, message text or appearance values you may want to recreate.

17. Support

For questions, support or feature requests, contact [email protected] or visit goalprevail.com.