documentation last update: 17th May 2022.
Please forward all your questions that are beyond the scope of this help file to our email via contact form here. Detailed changelog for plugin is here. Working demo website is located here.
If you override default and use custom templates in your_theme/woocommerce/ you need to make sure that templates are updated with those in plugin_dir/competitions-for-woocommerce/templates/ – otherwise new features might not show up on the site. Backing up your WP, WooCommerce and its database is something you should consider when updating and modifying this plugin – just in case.
Competitions for WooCommerce – Feature List
- completely integrated with WooCommerce via custom product type – competition
- 2 competition types – with and without ticket numbers with option to answer a question or solve a puzzle (skill based competitions)
- competition can have one or more winners
- competition ticket price can be zero, works with credit systems like TeraWallet / Credit payment gateways
- users can win single or multiple prizes
- refund tickets with single click if competition has failed
- instantly finish competition if max number of tickets was sold
- option to pick numbers from list or to assign number randomly without picking
- tickets table can be sorted in tabs if there are many tickets
- lucky dip button with option to select quantity – example: click here to buy 5 random tickets
- option to use alphabet prefix for ticket numbers (A1…A50, B1…B50, etc)
- option to extend lottery end date in case not enough tickets were sold (with all previously sold tickets – ticket rollover for failed competitions)
- manual competition relist and option to delete previous data after relisting
- automatic relist with option to save previous data (CSV export file saved automatically for previous competition)
- define minimum and maximum number of tickets available, max tickets per user, number of winners and multiple wins per user
- set start and end time for lottery
- entry lists page for competitions
- easy control of competitions listing – display competitions along with other products or on separate page
- widgets with ending soon, future, latest / recent, featured, recently viewed, random and my competitions
- email notifications (with editable templates) for competition win, fail, finish, no luck, lottery fail for customers, lottery extended
- competition product has lottery icon (label) on thumbnail
- competition single page has new tab “Competition History”
- users have My Tickets page under My Account or you can use shortcode [my_competitions] to display users competitions won and ones that user participates in
- option to enter winner manually – useful if you use 3rd party draw like random.org or national lottery numbers
- export competition participants with all details in CSV / Excel
- competition filter in product list (wp-admin)
- competition product has icon which describes different lottery status: active, finished, finished and paid, failed (wp-admin)
- plenty of shortcodes including shortcode to show my lotteries for logged in user
- make lottery from any type of existing WooCommerce product – simple, virtual or downloadable products
- manually delete any ticket via WooCommerce order management – deleting order deletes ticket
- login at later stage of checkout (guest checkout)
- Elementor support
- WooCommerce REST API support
- HPOS support
- WPML compatible, translation files
- Cronjobs required – if your host does not support 1 minute cronjobs you can use 3rd party cron service like easycron – plugin works with WP cron too
Installing Competitions for WooCommerce plugin
Prerequisite for this plugin is working WordPress and WooCommerce installation with theme that supports WooCommerce. You can install plugin via WordPress “Add New” plugin or upload plugin directory to using FTP / SFTP client to path_to_your_website/wp-content/plugins/ directory. Once you installed and activated it go to WooCommerce > System Status and make sure that you don’t have red colored errors (specially for WP memory limit). Make sure to enable inventory management in WooCommerce. Competitions for WooCommerce can not work with enabled option “Allow customers to place orders without an account” please turn it off in WooCommerce Accounts & Privacy settings.
Competitions for WooCommerce plugin requires cronjobs in order to end competition on time if there is no visitors on the site. If this is not important for your competition website you can skip cronjob setup. Relist cronjob is mandatory if you want to setup automatic relisting.
every minute: /usr/local/bin/curl --silent http://www.your-domain.com/?competitions-cron=checkevery hour: /usr/local/bin/curl --silent http://www.your-domain.com/?competitions-cron=relist
Path to curl can be /usr/local/bin/curl or /usr/bin/curl etc depending on your hosting setup. Cronjobs should be setup by your hosting support since they are familiar with cronjob details like curl path – afterall you are paying for hosting support. If your host does not support cronjobs we advise you to find alternative host (you can contact us for help and suggestions).
Setting up your first competition with Competitions for WooCommerce
Setting up new competition with Competitions for WooCommerce is similar to adding new WooCommerce product except you need to set couple more parameters specific to competitions:
-
- go to Products => Add Products
- add title, description, images, featured image, select category – all things you do when adding regular product
- in Product Data dropdown menu select Competition
- you will see new tab in left menu named Competition as on screenshot below and enter all details (options not marked optional on screenshot are mandatory and must be filled!):
- fill all required inputs like price, min / max tickets, number of winners, start and end competition dates
- publish competition – click on Publish button
- once you publish competition go to your shop or competition page and you should see new product – should look similar to screenshot below:
Overview of the competition workflow
Site owner creates new competitions which are published and then visible on website. Users can purchase tickets (with numbers) or entries (without numbers) in those published competitions and after end date is reached for competition they either lose or win competition. Owner now needs to fulfill / deliver prize or reward defined in competition description.
Competitions for WooCommerce – Options List
Plugin settings are located in WooCommerce Settings -> find tab Competitions. Settings are mostly self explainable. You can enable or disable showing past and future competitions. Another useful setting is whether to mix regular products with competitions or just show competitions on separate page (defined via Competitions Base Page dropdown, see screenshot):
Screenshot below shows WooCommerce Product List with active competitions. Competition status icons are not displayed on the screenshot – from WooCommerce 3.4.0 update, WooCommerce developers removed that column in product list (as a result of users’ feedback). There is way to restore it back using this plugin https://wordpress.org/plugins/woocommerce-product-type-column/ (status icon missing on screenshot below):
Custom Templating
If you need to customize plugin templates first thing to do is to copy content of plugin_dir/templates to your_theme/woocommerce so you do not overwrite changes when you update plugin. All changes and modifications should be done on files located in your_theme/woocommerce/.
List of Shortcodes
List of available shortcodes in Competitions for WooCommerce. Some shortcodes accept optional orderby and order attributes.
- shows competitions similar to products shortcode in WooCommerce –
[competitions ids="1,2,3,4,5" columns="4" orderby="title" order="asc"] - shows featured competitions –
[featured_competitions], [featured_competitions per_page="12" columns="4" order="desc" orderby="meta_value" future="no"] - shows recently added competitions –
[recent_competitions], [recent_competitions per_page="12" columns="4" order="desc" orderby="meta_value" future="no"] - shows ending soon competitions –
[ending_soon_competitions], [ending_soon_competitions per_page="12" columns="4" orderby="date" order="desc"] - shows future competitions (those that did not start yet) –
[future_competitions], [future_competitions per_page="12" columns="4" orderby="date" order="desc"] - shows finished competitions –
[finished_competitions], [finished_competitions per_page="12" columns="4" orderby="date" order="desc"] - shows competitions in which user participates and are active, user has to be logged in for this to work –
[my_active_competitions] - shows competitions in which user participated, user has to be logged in for this to work –
[my_competitions] - shows competitions which user won, user has to be logged in for this to work –
[won_competitions] - shows table in which each row contains competition name, date and winners –
[competitions_winners] - shows lucky dip button which adds defined quantity of tickets to cart, works only on single competition page –
[competition_lucky_dip_button qty="3"]
Please note that there is no paging when you use shortcodes (same as with WooCommerce shortcodes). Per page attribute means how many items will be displayed on that particular page without paging.
FAQ
- Do you have list of hooks and filters? – Yes, hook list is below:
woocommerce_product_options_competition competition_product_save_data wc_competition_close wc_competition_won woocommerce_competition_do_relist woocommerce_competition_do_extend wc_competition_participate_added wc_competition_participate_not_added wc_competition_participate wc_competition_cancel_participation wc_competition_cancel_participation_failed woocommerce_refund_processed woocommerce_order_partially_refunded woocommerce_order_fully_refunded woocommerce_order_refunded remove_participants_if_wrong_answer woocomerce_before_relist_competition woocomerce_after_relist_competition woocommerce_competition_duplicate_ticket_in_order_found wc_competition_delete_participate_entry wc_delete_competition_history_csv woocommerce_refund_processed woocommerce_competition_started wc_competition_fail wc_competition_min_fail woocommerce_shortcode_before_SHORTCODE-NAME_loop woocommerce_before_shop_loop woocommerce_after_shop_loop woocommerce_shortcode_after_SHORTCODE-NAME_loop woocommerce_shortcode_SHORTCODE-NAME_loop_no_results pre_get_competition_search_form woocommerce_competition_before_single_entry_table woocommerce_competition_single_entry_table woocommerce_competition_after_single_entry_table woocommerce_competition_before_participate woocommerce_competition_ajax_change_participate woocommerce_competition_participate_future wc_competition_before_ticket_numbersExample:
<?php add_action( 'wc_competition_fail, 'custom_function' ); ?>Here is list of all filters:
competition_add_participants_from_order competition_remove_participants_from_order woocommerce_order_fully_refunded_status woocommerce__competition_history_data woocommerce_competition_history_heading ticket_number_display_html competition_history_started_text competition_history_starting_text woocommerce_competition_history_heading woocommerce_competition_export_dir_path woocommerce_competition_export_filename woocommerce_competition_export_fields woocommerce_competition_participants woocommerce_competition_winners woocomerce_competition_history competitions_for_woocommerce_generate_random_ticket_numbers competition_numbers_to_alphabet_number_per_letter woocommerce_competition_entry_list_column_date woocommerce_competition_entry_list_column_default woocommerce_competition_entry_list_row_class woocommerce_competition_entry_list_columns woocommerce_competition_entry_list_sortable_columns woocommerce_competition_entry_list_totalitems woocommerce_competition_participating_message wrong_answer_display_item_meta remove_competitions_from_woocommerce_product_query {$shortcode}_shortcode_tag woocommerce_shortcode_competition_query woocommerce_product_query_max_rand_cache_count woocommerce_shortcode_products_query_results woocommerce_competition_bage ticket_number_tab_display_html woocommerce_competition_start_ticket_number woocommerce_quantity_input_min_competition woocommerce_quantity_input_max_competition competitions_for_woocommerce_displayname - Are there known issues? – Yes, if you have huge number of tickets with randomly assign ticket option you might get problems with php memory size which would have to be increased (or max number of tickets decreased).
- Does Competitions for WooCommerec work with object cache? – Yes, but we recommend to exclude its domain from cache, name of domains is competitions_for_woocommerce
- I use Elementor and I do not see anything in frontend? – Please go to Elementor Settings > Experiments and disable “landing pages”.