diff --git a/app/views/partners/requests/_history.html.erb b/app/views/partners/requests/_history.html.erb
index a7f56117f3..bc2048fce0 100644
--- a/app/views/partners/requests/_history.html.erb
+++ b/app/views/partners/requests/_history.html.erb
@@ -19,7 +19,7 @@
|
<% partner_request.item_requests.map do |item| %>
- <%= item.quantity %> <%= item.name %>
+ <%= item.quantity %> <%= item.name_with_unit %>
<% end %>
|
diff --git a/app/views/partners/requests/validate.html.erb b/app/views/partners/requests/validate.html.erb
index b596194994..02d7ef9c4d 100644
--- a/app/views/partners/requests/validate.html.erb
+++ b/app/views/partners/requests/validate.html.erb
@@ -22,7 +22,7 @@
<%= line_item.name %> |
<%= line_item.quantity %> |
<% if Flipper.enabled?(:enable_packs) && @partner_request.item_requests.any?( &:request_unit ) %>
- <%= line_item.request_unit %> |
+ <%= line_item.request_unit&.capitalize&.pluralize(line_item.quantity.to_i) %> |
<% end %>
<% end %>
diff --git a/docs/user_guide/bank/images/special_custom_units/Distribution_creation_from_a_request.png b/docs/user_guide/bank/images/special_custom_units/Distribution_creation_from_a_request.png
new file mode 100644
index 0000000000..8b5709341f
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/Distribution_creation_from_a_request.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/Email_with_units.png b/docs/user_guide/bank/images/special_custom_units/Email_with_units.png
new file mode 100644
index 0000000000..dca66b48eb
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/Email_with_units.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/Item_config_edit_button.png b/docs/user_guide/bank/images/special_custom_units/Item_config_edit_button.png
new file mode 100644
index 0000000000..f7c9b50e78
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/Item_config_edit_button.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/Item_config_list_shows_units.png b/docs/user_guide/bank/images/special_custom_units/Item_config_list_shows_units.png
new file mode 100644
index 0000000000..b6c5b20eb2
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/Item_config_list_shows_units.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/Item_config_request_units_checkboxes.png b/docs/user_guide/bank/images/special_custom_units/Item_config_request_units_checkboxes.png
new file mode 100644
index 0000000000..9dada47c0b
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/Item_config_request_units_checkboxes.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/New_Request_units.png b/docs/user_guide/bank/images/special_custom_units/New_Request_units.png
new file mode 100644
index 0000000000..ea6c657165
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/New_Request_units.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/New_Request_units_only_on_configured_items.png b/docs/user_guide/bank/images/special_custom_units/New_Request_units_only_on_configured_items.png
new file mode 100644
index 0000000000..49c55d54c8
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/New_Request_units_only_on_configured_items.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/Open_requests_with_units.png b/docs/user_guide/bank/images/special_custom_units/Open_requests_with_units.png
new file mode 100644
index 0000000000..781fbbbd50
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/Open_requests_with_units.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/Organization_level_units_setting.png b/docs/user_guide/bank/images/special_custom_units/Organization_level_units_setting.png
new file mode 100644
index 0000000000..537642262a
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/Organization_level_units_setting.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/Product_totals_calculation.png b/docs/user_guide/bank/images/special_custom_units/Product_totals_calculation.png
new file mode 100644
index 0000000000..a8f1164415
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/Product_totals_calculation.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/Request_confirmation_popup.png b/docs/user_guide/bank/images/special_custom_units/Request_confirmation_popup.png
new file mode 100644
index 0000000000..75c56b15d4
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/Request_confirmation_popup.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/Request_history_units.png b/docs/user_guide/bank/images/special_custom_units/Request_history_units.png
new file mode 100644
index 0000000000..c8eb4caae2
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/Request_history_units.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/Request_pick_list_pdf_with_units.png b/docs/user_guide/bank/images/special_custom_units/Request_pick_list_pdf_with_units.png
new file mode 100644
index 0000000000..2b0302b7f4
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/Request_pick_list_pdf_with_units.png differ
diff --git a/docs/user_guide/bank/images/special_custom_units/Success_page.png b/docs/user_guide/bank/images/special_custom_units/Success_page.png
new file mode 100644
index 0000000000..5a72c7c109
Binary files /dev/null and b/docs/user_guide/bank/images/special_custom_units/Success_page.png differ
diff --git a/docs/user_guide/bank/special_custom_units.md b/docs/user_guide/bank/special_custom_units.md
index fd76900b95..cd0140f275 100644
--- a/docs/user_guide/bank/special_custom_units.md
+++ b/docs/user_guide/bank/special_custom_units.md
@@ -1,16 +1,106 @@
-READY FOR REVIEW
-# Coming Soon -- Custom Units (opt-in feature)
+# Custom Units (opt-in feature)
-The number of items throughout the bank's view of the system is the number of units (e.g. diapers), but
-Partners often think in terms of packs of diapers. Because Banks were getting a lot of partners requesting the number of packs of diapers, instead of the number of diapers, we are introducing the ability for banks to allow the partners to request other units (e.g. packs)
+Custom Units addresses a long-standing problem that diaper banks, in particular, experience:
-In short, you'll be able to add custom units that they partners can request. The partners then can ask for, say, 'packs' of diapers. You will still have to translate those to the number of items when distributing, because there is a lot of variety in pack size across brands.
+- On the one hand, when you are tracking raw inventory, writing grant proposals, or working with the NDBN, you need to know how many individual diapers you distribute.
+- On the other hand, partners often want to work in terms of "packs" of diapers.
+Unfortunately, there isn't a standard number of diapers in a "pack", even in the same size (sometimes not even with the same manufacturer!), so we can't just convert one to the other.
+
+Custom Units is our solution so that the partners can order in terms of "packs", "boxes", "flats", etc, but you as the Bank still work in terms of individual diapers.
+
+You can specify different units (e.g. packs, boxes, flats) that the partners can use to order items, or the partner can still request them by the number of individual items ("units").
+
+You'll see the number of "packs" that the partner requested, but when creating the distribution you'll enter the number of individual items you actually distribute.
+
+(It's not a perfect solution!)
+
+We call this approach "Custom Unit" Requests.
+
+## Setting up Custom Units
+
+For a Bank to allow **Custom Units** to be used for Partner Requests, they must first configure which units are allowed and which items use custom units.
+
+### Set up your organization units
+
+First, set up all of the units that you want to use.
+
+- Click `My Organization`
+- Click `Edit`
+- In the "Custom Units" section, add in all of the custom units that you want to use
+ - Use lower-case singular names
+ - For example "pack", "box", and "flat"
+ - You can make up your own unit names
+ - Other unit ideas: "large pack", "small box", "1-month box"
+- Save changes
+
+
+
+### Set up units for specific items
+
+Next, you need to indicate which items should use custom units.
+
+- Go into the Inventory → Items & Inventory page, in the "Item List" section
+- Select an item, for example "Kids Pull-Ups (5T-6T)", click `Edit`
+
+
+
+- Indicate what units you would like Partners to use for requests of this item
+ - For example, you can select "pack" and "flat"
+
+
+
+Allowed units are then shown in the "Custom Request Units" column of the Item List.
+
+
+
+## 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 what is the units of their request.
+
+
+
+Units are only required for items that hae custom units configured. The request can also use "Units" to indicate that they want that number of unique items no matter the packaging.
+
+
+
+The confirmation screen shows the requested units.
+
+
+
+Once the request is confirmed, the Partner will receive a success page with the requested units.
+
+
+
+The email sent to the Partner will also contain the requested units.
+
+
+
+The Request History page shows the units alongside the item quantities.
+
+
+
+## Processing Requests with Units
+
+The request detail includes the units for each item.
+
+
+
+From the Request list, clicking `Print Unfulfilled Picklists` button generates a picklist. The request picklist PDF lists units when they are specified in the request.
+
+
+
+When you create a distribution from a request with units, you must enter the quantity of the items that are being distributed. **NOTE! The "Quantity - Total Units" is individual units!**. So if the Partner requested "9 boxes" of Pads, and each box has 10 Pads, then you should put "90" in the "Quantity - Total Units" field.
+
+
+
+Distributions are always created in terms of raw quantity, not requested units.
+
+## Other reporting
+
+From the list of requests, you can click on `Calculate Product Totals` to get a summary of the request quantities. These are separated out by the different units requested.
+
+
+
+Similarly you can export requests as a CSV and there are separate columns for each allowed item and unit.
-When this is ready for release, we will update this page, but to preview:
-[!NOTE] None of the following steps are available yet.
-- A bank that wishes to use custom units will add those units on their organization page
-- Then, for any Items that will use the custom units (you are not going to have the same units for car seats and diapers), you add them to that Item
-- At that point, the Partners will see a slightly different screen that will have them pick between "units" and the custom units (say, "packs")
-- When the bank sees the request, they will see the units that were chosen, but have to enter the total quantity for that item (in our example, the number of diapers)
-- The units the partner chose will show wherever we are showing the requested amounts (e.g. when viewing the request, when calculating Product Totals, when fulfilling the request, and in the pdf that is attached to their Distribution email.