MyListing Limited Promotions
The {CODICTS} MyListing Limited Promotions plugin adds a slot-limiting system to MyListing’s built-in Featured and Promoted listing functionality. Administrators can set a maximum number of featured or promoted listings allowed per listing type and per WooCommerce package, creating scarcity and controlling how many listings can hold premium positions at any time.
Installation & Activation
Start by downloading the plugin from the Downloads page on your dashboard on the CoDicts website.
After downloading, install and activate the plugin in WordPress by navigating to “Plugins” > “Add New” > “Upload Plugin” and selecting the downloaded zip file. Click “Install Now” and then “Activate”.
On activation, the plugin automatically copies its template overrides into your child theme directory. Navigate to “Limited Promotions” in the WordPress admin sidebar to configure slot limits.
Important: Both the MyListing theme and a MyListing child theme must be active. Without a child theme, the plugin displays an error notice and does not load.
Key Features
| Feature | Description |
|---|---|
| Featured Slot Limits | Set a maximum number of featured listings allowed per WooCommerce listing package, per listing type. |
| Promoted Slot Limits | Set a maximum number of promoted listings allowed per WooCommerce promotion product, per listing type. |
| Visual Slot Indicators | Displays “Slots available: X” on both the package selection step and the promotion modal, with “No slots available” messaging and disabled buttons when full. |
| Real-Time Checking | The promotion modal checks slot availability in real time via AJAX before letting users purchase. |
| Checkout Enforcement | Automatically removes promotion items from WooCommerce orders if slots filled up between cart addition and checkout. |
| Admin Save Enforcement | Automatically unpublishes a listing if an admin marks it as featured when no slots are available. |
| Custom Priority Support | Override which priority values count toward slot limits for advanced configurations. |
| No-Package Inclusion | Optionally count listings without a package toward all slot limits. |
| Cross-Package Inclusion | Optionally include listings from specific listing packages in the promoted slot count for a promotion product. |
The Problem It Solves
By default, MyListing allows unlimited listings to be featured or promoted. If every listing owner purchases a featured package, the “featured” status loses its value — there’s no exclusivity. This plugin lets you create real scarcity by capping how many listings can hold premium positions at any given time.
For example, you might limit your “Premium Plan” to only 10 featured restaurant listings. Once all 10 slots are filled, the next user sees “No slots available” and cannot purchase that package until a slot opens up.
How It Works
The plugin enforces slot limits at four distinct points to prevent any way of bypassing the restrictions:
1. Package Selection (Add Listing) — When a user is choosing a listing package, each package card shows “Slots available: X”. If no slots remain, the buy button is replaced with a “No slots available” message and the package cannot be selected.
2. Promotion Modal (User Dashboard) — When a user clicks “Promote” on a listing, the modal checks slot availability in real time. Promotion products with no remaining slots are disabled and cannot be purchased.
3. Admin Listing Save — If an admin marks a listing as featured in the backend when no slots are available, the listing is automatically set to draft (unpublished) with an admin notice explaining why.
4. WooCommerce Checkout — If slots fill up between the time a user adds a promotion to their cart and completes checkout, the promotion item is automatically removed from the order with a note explaining the removal.
Configuring Slot Limits
Navigate to “Limited Promotions” in the WordPress admin sidebar.
The settings page lists all registered MyListing listing types. For each listing type:
Step 1 — Enable Slot Limits
Check the “Enabled?” checkbox to activate slot restrictions for that listing type. Until enabled, no restrictions apply.
Step 2 — Set Featured Slot Limits
The left column shows “Listing Package Slots (Featured)” — all WooCommerce listing packages that have the “Feature Listings” option enabled.
For each package, enter the available slots — the maximum number of featured listings allowed for this package + listing type combination.
| Value | Meaning |
|---|---|
A positive number (e.g., 10) | Maximum that many featured listings for this package. |
-1 | Unlimited — no slot restriction for this package. |
Step 3 — Set Promoted Slot Limits
The right column shows “Promoted Slots” — all WooCommerce promotion products that are purchasable.
For each promotion product, enter the available slots using the same logic (positive number to limit, -1 for unlimited).
Step 4 — Save Changes
Click “Save Changes”. The settings page shows real-time status for each package:
| Indicator | Meaning |
|---|---|
| Current used slots: X | How many listings currently occupy slots for this package. |
| “Full” badge | Used slots equal the configured limit. |
| “Limit Exceeded” badge | Used slots exceed the limit (e.g., if you reduced the limit after listings were already featured). |
Advanced Configuration
Custom Priorities
By default, MyListing uses priority values: 0 = Normal, 1 = Featured, 2 = Promoted. If your site uses additional custom priority levels, you can configure which priority values count toward each package’s slot limit.
1. Check “Use custom priorities?” on the package.
2. Enter one or more priority IDs separated by commas (e.g., 1,2).
For example, setting custom priorities to 1,2 for a featured package means that listings with either priority 1 or priority 2 count toward that package’s featured slot limit.
Including No-Package Listings
Check “Include no packages?” to count listings that have no package assigned (e.g., listings created manually by an admin) but still have a featured or promoted priority toward every package’s slot usage.
This effectively reduces the available slots for all packages. The settings page shows “Used slots with no package: X” for reference.
Including Listing Packages in Promoted Slots
For promoted slots only, each promotion product has an “Include listing package?” option. When enabled, you can select listing packages from a dropdown. Listings belonging to those selected packages that also have the matching priority will count toward the promotion product’s slot usage.
This is useful when you want featured listings from certain packages to also occupy promotion slots, creating a cross-package dependency.
Example Configuration
A restaurant directory site with two listing packages and two promotion products:
| Package / Product | Type | Slot Limit | Effect |
|---|---|---|---|
| Basic Plan | Featured | -1 | Unlimited featured restaurants with Basic Plan. |
| Premium Plan | Featured | 10 | Maximum 10 featured restaurants with Premium Plan. |
| 7-Day Boost | Promoted | 5 | Maximum 5 promoted restaurants with 7-Day Boost. |
| 30-Day Boost | Promoted | 3 | Maximum 3 promoted restaurants with 30-Day Boost. |
When the 5th restaurant is promoted with “7-Day Boost,” the next user attempting to promote with the same product sees “Slots available: 0” and the option is disabled. They can still use “30-Day Boost” if it has remaining slots.
Template File Management
The plugin overrides two MyListing templates by copying modified versions into the child theme:
| Template | Purpose |
|---|---|
| choose-package.php | Adds slot availability display and “No slots available” messaging to the package selection step during add listing. |
| choose-promotion.php | Adds real-time AJAX slot checking, loading states, and disabled states to the promotion modal in the user dashboard. |
Templates are automatically installed on activation and removed on deactivation. They are force-reinstalled when the plugin version changes.
Note: If you manually customize these templates in your child theme, your changes may be overwritten on plugin updates. If the plugin is deactivated, the original MyListing templates take effect again.
Frequently Asked Questions
Why is a child theme required?
The plugin copies modified template files into the child theme directory to override MyListing’s default package selection and promotion modal templates. Without a child theme, the plugin has nowhere to safely place these files.
What happens when all slots are full?
Users see “No slots available” and the buy/promote button is disabled. They cannot purchase or apply that package or promotion. If a slot opens up (e.g., a featured listing expires or is unfeatured), the slot becomes available again automatically.
What if a slot fills up after a user adds a promotion to their cart?
The plugin checks slot availability again at checkout. If no slots remain, the promotion item is automatically removed from the order with an explanatory note. This prevents race conditions.
What happens if an admin features a listing when slots are full?
The listing is automatically set to draft (unpublished) and an admin notice displays: “Current featured slots are full, the listing has been unpublished.”
Can I set different slot limits for different listing types?
Yes. Each listing type has its own independent configuration. You can enable slot limits for restaurants but leave hotels unlimited, for example.
Can I set unlimited slots for a specific package?
Yes. Enter -1 as the available slots value for any package you want to leave unrestricted.
What does “Limit Exceeded” mean on the settings page?
This appears when the number of currently featured/promoted listings exceeds the configured limit. This can happen if you reduce a slot limit after listings are already featured. Existing listings are not automatically unfeatured — but no new listings can be featured until the count drops below the limit.
Do slots open up when a listing’s promotion expires?
Yes. Slot counts are calculated in real time by querying currently published listings. When a promotion expires and the listing is no longer promoted, the slot is freed automatically.
What are custom priorities for?
By default, MyListing uses priority 1 for Featured and 2 for Promoted. If your site uses additional custom priority levels (e.g., 3 for “Super Featured”), custom priorities let you define which priority values count toward each package’s slot limit.
What does “Include no packages?” do?
It counts listings that have no WooCommerce package assigned (e.g., manually created by an admin) but still have a featured/promoted priority toward every package’s slot usage. This reduces available slots across all packages.
Troubleshooting
Slot Limits Not Being Enforced
| Cause | Solution |
|---|---|
| Listing type not enabled | Check the “Enabled?” checkbox for the relevant listing type on the settings page. |
Slot limit set to -1 | A value of -1 means unlimited. Enter a positive number to enforce a limit. |
| Templates not installed | Deactivate and reactivate the plugin to force-reinstall template files into the child theme. |
“Slots Available” Not Showing on Package Selection
| Cause | Solution |
|---|---|
| Template override not installed | Deactivate and reactivate the plugin to reinstall templates. |
| Package doesn’t have “Feature Listings” enabled | Only packages with the WooCommerce “Feature Listings” option enabled appear in the featured slots settings. Check the WooCommerce product configuration. |
| Child theme conflict | If you have a custom choose-package.php in your child theme, it may be conflicting with the plugin’s version. Back up your custom version and reactivate the plugin. |
Promotion Modal Not Checking Slots
| Cause | Solution |
|---|---|
| Template override not installed | Deactivate and reactivate the plugin. |
| JavaScript error | Check the browser console (F12 → Console) for errors that might prevent the AJAX slot check from running. |
| AJAX blocked | Ensure your site’s admin-ajax.php endpoint is accessible. Some security plugins may block AJAX requests. |
Admin Save Unpublishing Listings Unexpectedly
| Cause | Solution |
|---|---|
| Featured slots are full | Check the settings page for the listing type — if featured slots show “Full”, no new listings can be featured. Increase the slot limit or remove a featured listing to free up a slot. |
| “Include no packages” is active | Listings without packages may be consuming slots. Check the “Used slots with no package” count on the settings page. |
Promotion Removed from Order at Checkout
| Cause | Solution |
|---|---|
| Slots filled between cart and checkout | This is the plugin’s checkout enforcement working as designed. Another user filled the last slot before checkout completed. The order note explains which item was removed and why. |
“MyListing Theme Not Detected” or “Child Theme Not Detected” Error
Both the MyListing theme and a MyListing child theme must be installed and active. Go to Appearance → Themes to verify.
For further support, visit codicts.com or contact us at support@codicts.com.