User guide: document per-Item request limits (#5386)

docs/user_guide/bank/inventory_items.md

@@ -83,6 +83,8 @@ The fields are:
 - On hand minimum quantity -- This is a bank-wide on-hand minimum quantity of the Item -- being below this triggers the Item appearing in your low inventory report in red.
 - On hand recommended quantity -- This is the amount you want to have on hand -- if you don't have this, it will appear in the low inventory list on your dashboard, just not in red.
 - Package size -- If you use this, the calculated number of packages for the Item will appear on the distribution printout, unless you hide it when [customizing your bank](getting_started_customization.md).
+- Request limit (individual items) -- An optional hard cap on how many of this Item a Partner can ask for in a single Request when they are requesting by individual items.  If a Partner asks for more than this, their Request is rejected with an error telling them the limit, and they'll need to lower the quantity before they can submit.  Leave it blank if you don't want a limit.  See [Request limits](#request-limits), below.
+- Additional Custom Request Units -- This only appears if your bank has set up [custom units](special_custom_units.md).  Check each unit (e.g. "pack") that Partners should be able to request this Item in.  Beside each checked unit you can also enter a request limit for that unit.
 - Item visible to partners -- This is useful if you have Items that you do not want the partners directly requesting.   Uses include: Items you don't get very often,  or Items you only have because they are going into kits you haven't assembled yet. You can uncheck this to hide those Items from all your partners.
 
 #### Filtering your item list
@@ -96,6 +98,23 @@ Clicking "Edit" beside an Item on the Item list lets you edit the Item definitio
 ![Edit Item page](images/inventory/inventory_items_edit.png)
 [!NOTE]  Value per Item is in dollars on this screen. 
 
+#### Request limits
+Some banks find that a Partner will occasionally request far more of an Item than the bank can supply.  The Partner's [Quota](pm_adding_a_partner.md#quota) only gives a friendly warning, and applies to the whole Request. If you need an actual limit on a specific Item, use the request limit fields on the Item.
+
+![Request limit fields on the Item edit page](images/inventory/inventory_items_request_limits.png)
+
+1. "Request limit (individual items)" is the most a Partner can ask for in one Request when they request the Item by individual items (i.e. "units").
+2. If the Item has [custom units](special_custom_units.md), each checked unit has its own "limit" field.  In this example, a Partner can request at most 4 packs of this Item.
+3. The limit field is disabled for units that aren't checked.
+
+Leave a limit blank if you don't want one -- a blank limit means there is no limit for that way of requesting.
+
+When a Partner submits a Request that goes over a limit, the Request is not saved, and they see an error like this at the top of their Request form, so they can adjust the quantity and try again:
+
+![Partner's error message when they exceed a request limit](images/special_custom_units/Request_limit_error.png)
+
+[!NOTE]  Request limits apply to each Request on its own -- they are not a monthly or yearly allowance.  They apply to quantity-based Requests (including ones you enter on a Partner's behalf), but not to child-based or individual-based Requests, and they don't restrict what you can put in a Distribution.
+
 #### Adding a new Item
 To add a new Item,  click the "+ New Item" button on this page.   It will bring up the same page as "Editing an Item", above (only, of course, with none of the fields completed).
 

docs/user_guide/bank/special_custom_units.md

@@ -44,15 +44,26 @@ Next, you need to indicate which Items should have Custom Units.
 
 ![Item config edit button](images/special_custom_units/Item_config_edit_button.png)
 
-- Indicate what units you would like Partners to be able to use when requesting this Item
+- Under "Additional Custom Request Units", check each unit you would like Partners to be able to use when requesting this Item (1)
   - In the example below, we picked "pack" and "flat"
+- Optionally, enter a request limit beside each checked unit (2).  This is the most of that unit a Partner can ask for in a single Request.  (See [Request limits](#request-limits), below.)
 
 ![Item config request units checkboxes](images/special_custom_units/Item_config_request_units_checkboxes.png)
 
 Allowed units are then shown in the "Custom Request Units" column of the Item list.
 
 ![Item config list shows units](images/special_custom_units/Item_config_list_shows_units.png)
 
+### Request limits
+
+Each unit on an Item can have its own request limit, and there is a separate "Request limit (individual items)" field for when the Partner requests in individual items.  A limit is the most a Partner can ask for in one Request. Leave a limit blank if you don't want one.
+
+If a Partner submits a Request that exceeds a limit, the Request is rejected and the Partner sees a message naming the Item, what they asked for, and the limit -- for instance, "Kids Pull-Ups (5T-6T): You requested 10 packs, but are limited to 4 packs."  They can then change the quantity and resubmit.
+
+![Partner's error message when they exceed a request limit](images/special_custom_units/Request_limit_error.png)
+
+[!NOTE] Limits are checked against the unit the Partner chose.  If a Partner asks for 10 packs, we compare that to the "pack" limit, not to the individual-item limit -- we don't know how many items are in a pack!
+
 ## How Partners use Custom Units in Requests
 
 When a Partner places a Request, they fill out a form indicating the Items they are requesting. If the Item is configured to have Custom Units, they must now select the units for that Item.