Knowledgebase

Portal Home > Knowledgebase > Sysprosium WHMCS Modules > Product Quota Manager

Product Quota Manager

[You can order the Product Quota Manager Here]



The Product Quota Manager is a simple to use module that adds product and product group quota management for administrators.  With this module you are able to limit the number of times a product may be purchased or the number of products that may be purchased from a specific group.  You can also individualize each product by deciding whether that product should count against the group quota (if one is set), and if that product should have a higher quota than the group quota.  This module also allows you to set custom alert messages that the customer will see if they attempt to purchase a product that would exceed any quota limits.

You can jump to any point in this guide via these links:

  1. Installation Guide Instructions on installing the module
  2. Module Layout - The admin interface
  3. Quota Settings- Overview of the options for each product and group
  4. Quota Alert Messages - A look at the alert messages and shortcuts
  5. Order of Operations - An explanation of the logic behind the system
  6. Frequently Asked Questions - FAQ
  7. A Practical Example - An example of the system in action



Installation
Installation is straight forward for this module.

  1. Log into your account and purchase either the Trial or Lifetime License for the Product Quota Manager
  2. Download the module from the download area
  3. Unzip the pqm.zip file
  4. Upload the product_quota_manager folder to /path/to/modules/addons
  5. Go to Setup->Addons and activate the Product Quota Manager
  6. Enter your license key that was generated when you purchased the module
  7. Set your permissions
  8. Set the max value for the quota drop down. The default is 50. If you wish to limit a product or group to a value greater than 50 but less than unlimited, you'll need to change this. If not, you can leave it as the default.
  9. You're done. Painless for far, yes?



Layout
Go to Addons->Product Quota Manager. If your license check is verified, you should see a screen that looks like this:

Preview image for the Product Quota Manager

This shows all of the product groups that you have configured within WHMCS Setup->Products/Services. Also shown is whether or not the group is hidden, any group quota, the alert message, and if it is activated.

If you click on the Green plus icon it will show you the products you have configured within that product group as shown below:

Preview image for the Product Quota Manager

As you can see, the same information is present but with the addition of a few more options.  Each product has the option to be set as Product Exempt and Group Exempt. This is where the real power of the system is found. More on that in the next section.




Settings


  1. Product Group Settings
    1. Quota: This quota is the maximum number of purchased products that a customer can have on their account. It ignores any products that have been terminated. For example: if you set the product group limit to 3 and a customer has previously purchased two items from this group and tries to purchase two more, the system will deny that purchase at checkout and inform them with the message that you set as the alert.
    2. Alert: The alert message is what the customer sees when they are declined a purchase. You can use several shortcuts in the alert message to help tailor the message. I will go over the alert message shortcuts in greater detail in another section.
    3. Activate: Click on the Green plus icon and the quota will be activated. Alternatively you can click on the Check mark icon to disable the quota.
    4. Remove: Clicking on the Red x iconwill let you reset any quota settings for that specific product or product group. It does not affect any other product groups or products within that group. It is a quick way to undo any previous settings.
  2. Product Settings
    1. Quota: Each product can have an individual quota set. That means that you are able to limit products on a need-basis. If you only want one product within a group to be limited by a quota, you set set that.
    2. Product Exempt: This setting is only useful if you have a Product Group quota set for the group this product is in. This setting will remove any quota from the product itself, basically making it unlimited. For example: if you set a product group quota of 1, and you set a product within the group as Product Exempt, a customer will be able to buy as many of that product as they like, but the total number of this product will count against the group quota. I'll go deeper into this setting in the FAQ section.
    3. Group Exempt: As with the Product Exempt setting, this setting is only useful if you have a Product Group quota set. When you enable Group Exempt for a product within that product group, the limit of the product still applies (if you have one set) but any purchases of this product do not count against the group quota when determining whether or not the order will be accepted. For example: You have a Group Quota of 3 and you set a product to Group Exempt, when a customer attempts to purchase this product, the system will exclude any previous purchases of this product from the total number of previous purchases made from the group. It also will not count this product in the cumulative total within their cart (providing they have other items). Any limit set for the product will apply. I'll go deeper into this setting in the FAQ section.
    4. Alert: The alert message is what the customer sees when they are declined a purchase. You can use several shortcuts in the alert message to help tailor the message. I will go over the alert message shortcuts in greater detail in another section.
    5. Activate: Click on the Green plus icon and the quota will be activated. Alternatively you can click on the Check mark icon to disable the quota.
    6. Remove: Clicking on the Red x iconwill let you reset any quota settings for that specific product or product group. It does not affect any other product groups or products within that group. It is a quick way to undo any previous settings.



Alerts
Alerts are the messages that are shown to the customer when they go over a pre-set quota. They can be as simple or as informative as you'd like. Each alert lets you use several shortcuts when crafting the message in order to provide as much information as you want.

  1. Shortcuts
    1. {PRODUCTNAME} - The product name
    2. {GROUPNAME} - The group name that the product belongs to
    3. {QUOTA} - The quota that you have set for the product or product group
    4. {CARTQTY} - The quantity of the product in the customers cart
    5. {OWNEDQTY} - The quantity of any previous purchase of this product by the customer, or the quantity of all previous purchases within the product group
    6. {CUMULATIVE} - The cumulative total up to this product or product group. This includes previous purchases and any purchases in the customers cart that would be approved. The module works on the First In, First Out method. When a customer checks out, it starts with the first item they placed in their cart. If they are approved to buy it (they are under the quota limit), then the quantity is added to the cumulative total. The next product is checked against the cumulative total, if approved, the quantity is added to the cumulative total. Repeat. This prevents customers from adding one product several times in order to avoid any quota limits. You can think of it as a running total.
    7. {INCQTY} - Included Quantity. This is similar to {CUMULATIVE} except that it adds the {CARTQTY} to the {CUMULATIVE} value. This would allow you to craft an alert message similar to: {NAME} has a quota limit of {QUOTA}. Including your {OWNEDQTY} previous purchases of this item, your total quantity would be {INCQTY}, which exceeds the quota set.
    8. {OVERBY} - The quantity number that would be in excess of the quota. This is the difference between {INCQTY} and {QUOTA}. To continue with the previous example, you could then craft a message such as: {NAME} has a quota limit of {QUOTA}. Including your {OWNEDQTY} previous purchases of this item, your total quantity would be {INCQTY}, which exceeds the quota by {OVERBY}.

As you can see, the shortcuts give you a lot of options when crafting your alert messages. You don't need to use them but if you want to, you can. Here is an example of an alert message that I set and what the customer would see:

You are limited to only {QUOTA} purchase from the {GROUPNAME} group. You have previously purchased {OWNEDQTY} from this group. Including what you have purchased in the past, plus the {INCQTY} items in your cart, this would exceed the quota by {OVERBY}.

Alert Message for the Product Quantity Manager




Order of Operations

So, at this point you might be questioning how the system determines when a purchase should be approved or when it should be declined. That is where the order of operations comes in. In a nutshell the system runs through the checks in the following order:

  1. Product Quota - Is the product, including previous purchases, under the quota
  2. Group Quota - Is the product, including previous purchases of all items from this group (excluding terminated items), under the group quota

  3. That is the most basic of operations, but recall that you can set exemptions. So, on a deeper level, it really progresses in like this:

    1. If the product does not have a quota set and is not part of a product group that has a quota then the purchase will be automatically approved
    2. If the product is set both Product Exempt and Group Exempt then the purchase the product will be automatically approved as it is out of bounds for both the product limit (Product Exempt = Unlimited) and group limit (Group Exempt = does not calculate in any group quota limits)
    3. Is there a product or product group limit set for this item? If yes, continue...
    4. Is the product set Product Exempt? If yes, then the purchase is approved. If you set a quota for the product AND set the Product Exempt flag, the exemption will override the quota (Product Exempt = Unlimited)
      1. Is the product set Group Exempt? The purchase will be approved but the system needs to determine if the quantity will affect future purchases
        1. If yes, then the quantity of the purchase is not considered in current or future products group quotas (See #2)
        2. If no, then the quantity of the purchase is considered in the current quota limit and future product group quotas.
    5. If the product is not set Product Exempt, then it checks to see if the quantity of this purchase plus any previous purchases (of this item) is less than the quota. If it is, then the system continues, otherwise the purchase is declined.
      1. If the product is set Group Exempt?
        1. If yes, then the purchase is approved, and all previous and future purchases of this item will not be considered when determining the group quota
        2. If no, the system moves on to the next phase, which it looks at product group quotas
    6. Is the product quantity less than the Product Group Quota when considering all previous purchases of items and any cumulative quantities of items in the cart (remember First In, First Out) from this product group?
      1. If yes, then the product purchase is approved and the quantity is considered in future purchases from this product group. Also, the quantity will be added to the cumulative total in the event that the customer has more items in their cart.
      2. If no, then the product purchase is denied for this item. The alert message you have set will be shown to the customer so that they may adjust the the quantity of items in their cart



    FAQ

    We are now to the part of the document where I'll try to add in some better explanations along with practical examples. If your question is not answered or you still need help, please submit a ticket or email modules [@] sysprosium [.] com and we will try to address any issues or concerns you have.

    Hey, can you explain the shortcuts again?

    Absolutely! I know that they can be a bit confusing to understand exactly what information they are going to return. Even I have to think about them sometimes and I wrote the module! Let me try my best to clarify what you can expect. The examples will demonstrate what the outcome of the alert would be. I will continue to build on the previous example (thus the product name, quantity, quota, etc will remain the same):

    {PRODUCTNAME} or {GROUPNAME} - This is going to be replaced by the product name or the product group name.

         Example: If your product named 'Premier Web Hosting' and you set an alert message to:
         Alert Message: {PRODUCTNAME} quota exceeded
         What Customer Sees: Premier Web Hosting quota exceeded.


    {QUOTA} - This will be replaced by the quota limit for either the product or the product group, depending where you set it. If the alert is set for a product, then the quota will be the quota for that product. The same with Product Group.
         Example: If your product has a quota of 2 and you set an alert message to '
         Alert Message: {PRODUCTNAME} has a quota limit of {QUOTA}.
         What Customer Sees: Premier Web Hosting has a quota limit of 2.


    {CARTQTY} - This is the quantity of the product in the customers cart.
         Example: If the customer tries to purchase 1 more of the Premier Web Hosting product with the quota limit is 2 and you set the following alert
         Alert Message: {PRODUCTNAME} has a quota limit of {QUOTA} thus your purchase of {CARTQTY} would exceed the quota limit.
         What Customer Sees: Premier Web Hosting has a quota limit of 2 thus your purchase of 1 would exceed the quota limit.


    {OWNEDQTY} - This will be replaced by the total of any previous purchases of the product or the sum of any previously purchased products within the product group.
         Example: Same situation as above, but this time you set the alert message to:
         Alert Message: {PRODUCTNAME} has a quota limit of {QUOTA}, thus your purchase of {CARTQTY}, in addition to your previous purchase of {OWNEDQTY}, would exceed the quota limit.
         What Customer Sees: Premier Web Hosting has a quota limit of 2, thus your purchase of 1, in addition to your previous purchase of 2, would exceed the quota limit.


    {CUMULATIVE} - Now we are getting to more of the fun tags. The previous tags were all fairly self-explanatory. {CUMULATIVE} will be replaced by the running total in the customers cart. The way the system works is, as each product is approved, it is added to a cumulative total so that a customer can't bypass the system by purchasing multiple copies of an item with a quantity of 1 each. This shortcut is really meant for Product Group quotas and not individual products. You can use it for individual products if you'd like, but unless the customer added the item to their cart more than once, {CUMULATIVE} will be the same as {CARTQTY}. On the other hand, if they added the product to their cart three times, each time with a quantity of 1, then {CUMULATIVE} will increase for each time the product purchase was approved. {CUMULATIVE} does not include the quantity of the denied purchase, only those that were approved before it

    For a Product Group quota, {CUMULATIVE} makes more sense. For each product in the customers cart that is approved, the quantity is added (unless the product is set Group Exempt). This is how it keeps a running total of all the products from that product group that do not exceed the group quota. To continue the example, this time including a group product quantity:

         Example: You have decided to set a group quantity quota on the product group that the Premier Web Hosting package is part of instead of setting a quota limit on the individual packages. We will call this product group 'Web Hosting Packages'. Because your rates are so low, you decide that you only want a client to be able to buy 3 items from the product group before they are denied. At this point, the customer has previously purchased 2 of the Premier Web Hosting packages. You set an alert message to:
         Alert Message: {GROUPNAME} has a quota limit of {QUOTA}, thus your purchase of {CARTQTY} {PRODUCTNAME}, along with your cumulative total of {CUMULATIVE}, which would exceed the quota limit.
         Example: Now, when the customer tries to checkout with 1 more Premier Web Hosting package and 1 Basic Web Hosting package, they would see the message:
         What Customer Sees: Web Hosting Packages has a quota limit of 3, thus your purchase of 1 Basic Web Hosting package, along with your cumulative total of 3, would exceed the group quota limit.


    {INCQTY} - This shortcut is almost identical to the one above except that it INCLUDES the quantity of the item rather than excluding it. Because the purchase of this product was rejected, the quantity will not be added to the cumulative total.
         Example: Using the same scenario as above, you could write the alert message as:
         Alert Message: {GROUPNAME} has a quota of {QUOTA}, thus your purchase of {CARTQTY} {PRODUCTNAME} package, along with the {OWNEDQTY} previous purchases from this product group (and any in your cart) would bring your total to {INCQTY}, which exceeds the group quota.
         What Customer Sees: Web Hosting Packages has a quota limit of 3, thus your purchase of 1 Basic Web Hosting package, along with the 2 previous purchases from this product group (and any in your cart) would bring your total to 4, which exceeds the group quota.

    Remember, the {INCQTY} and the {CUMULATIVE} both include any items in the cart that have already been approved. So, in this case, the Premier Web Hosting package would have been approved, bring the cumulative quantity to 3. That is why the Basic Web Hosting package failed the group quota check. Including the quantity of that item, plus the cumulative quantity, would bring the total to 4.

    {OVERBY} - And this bring us to the last shortcut. {OVERBY} is replaced with the quantity that exceeded the quota. This one is fairly straight forward. Again, using the previous examples, you could expand upon the information provided by doing something like this:
         Example: Using the same scenario as above, you could write the alert message as
         Alert Message: {GROUPNAME} has a quota of {QUOTA}, thus your purchase of {CARTQTY} {PRODUCTNAME} package, along with the {OWNEDQTY} previous purchases from this product group (and any in your cart) would bring your total to {INCQTY}, which exceeds the group quota by {OVERBY}.
         What Customer Sees: Web Hosting Packages has a quota limit of 3, thus your purchase of 1 Basic Web Hosting package, along with the 2 previous purchases from this product group (and any in your cart) would bring your total to 4, which exceeds the group quota 1.


    What about this Product Exempt and Group Exempt option?

    These two flags can get a bit tricky if you're not careful. I know that I have received unexpected results by using them, only to realize that the results were correct but my assumption of what would happen, was not. I'll try to provide you with enough information that you're not caught by any surprises.

    Product Exempt - Product Exempt makes the product quota unlimited, regardless what the drop down box might indicate. It basically acts as an override flag for the product. When you set a product to Product Exempt, Group Quotas do not apply to the purchase of this product.
     
         Example
    : The System Monitoring Product Group has a limit of 1. A client can only purchase one System Monitoring service at a time. But, within that product group you offer SMS Credits. These credits are prepaid text alerts. Obviously you would not want to limit the number of credits someone can buy even though the product group has a limit of one. So, you set the Product Exempt flag on the SMS Credits package and then activate it.
         Results: A customer buys one Silver System Monitoring package and the following week he decides to buy some SMS Credits. Normally the transaction would fail because you have a Product Group quota set, but because this product is Product Exempt, the transaction will succeed.


    There is a catch, though... If the client bought the SMS Credits first and then wanted to add a System Monitoring package at a later date, the system would deny the purchase because, while the Product Exempt removes the limitation from the product (overrides the group limit), the product purchases still count against the group quota. This leads us into the Group Exempt flag.

    Group Exempt - Group Exempt causes any previous purchases of a product to not count in the total number of purchases from the Product Group. You would use this if you wanted to set the Group Product quota to one value but allow the purchase of a product to be higher than the product group quota, and specifically, not count against the group quota.

         Example
    : Using the previous example, you decide to fix the situation by setting the Group Exempt flag on the SMS Credits package.
         Results: Now, if a client decides to buy the SMS Credits first and later purchase a the Silver System Monitoring package, they will not be denied. The Silver System Monitoring package will count against the group quota (thus, they will have reached their limit of 1) but purchases of the SMS Credits package will not. Of course, in this example, the SMS Credits package is still limited by the quota limit set for the package. As long as they do not exceed the product quota limit for the package, their purchases will succeed.

    If you want to make a package both unlimited and not count against the group quota limit, set both flags to Yes. With the previous example, you probably don't want to limit the number of credits they can buy, and you don't want it to count against their group purchase quota, so you'd set both flags. Now they can buy as many SMS Credits as they want.

    It is very important to remember that any product you set as Group Exempt is not taken into consideration when determing if products from that group exceed the group quota limit.

    Previous purchases will not be figured into the total quantity of products that a customer has purchased from that group, nor will any items in their cart be added to the cumulative total.  So, if you are receiving some unexpected results, check if you have a product or products set with the Group Exempt flag. Chances are you do (at least it has always been that in my case).




    A Practical Example

    These are screenshots that I took that will show you a real-world demonstration of the above.

    First, I'm going to set the quota limits. As you can tell, I have some very creative product names in my product group


    As you can see, I have a group quota limit of 5 and each product has a limit of 2. That means that I cannot have more than 2 of any given product and I cannot have more than 5 total in from the product group.


    This image shows the items in my cart


    I'm going to purchase 2 of Product 4, 2 of Product 5, and 1 on Product 6. All of those fall within the defined limits. No product has a quantity greater than 2 and, if you add up the quantities for all the items, it is 5, which does not exceed the group limit.


    And... success!

    The order went through without an issue.

    And just to prove it, here is a shot of My Products


    You can see that the items are on my account and in good standing.


    Now, I'm going to try to purchase more items from that group. I'm going to add 3 of Product 4, 3 of Product 5, and 1 of Product 6. Product 4 and Product 5 should both exceed the Product Quota of 2 and thus fail. Product 6 does not exceed the Product Quota of 2 but would exceed the Group Quota of 5 (5 items from my previous order plus this one would be 6)


    Everything is in my cart. Lets see what happens when I try to purchase them.


    Oops... well, that failed.


    As you can see, from my very boring alert messages, each product failed for the correct reason. Both products 4 and 5 exceed their individual product quota and Product 6 exceed the group quota.

    You can also see how the shortcut values changed depending on which alert message was triggered. The {OWNEDQTY} changed to 5 for Product 6 because it failed the Product Group Quantity check. The owned quantity for the product group is the total of all previously purchased products that are in the product group, excluding any products that have been terminated or any product that is set to Group Exclude (as products that are set to Group Exclude do not count in the owned total nor do they count against any cumulative total).

 

Was this answer helpful?

Add to Favourites Add to Favourites Print this Article Print this Article