Supplier price note (#13027)

* add extra information to form

* Updated documentation

* Updated UI

* Fix broken link

docs/docs/concepts/units.md

@@ -57,7 +57,7 @@ The [unit of measure](../part/index.md#units-of-measure) field for the [Part](..
 
 ### Supplier Part
 
-The [supplier part](../part/index.md/#supplier-parts) model uses real-world units to convert between supplier part quantities and internal stock quantities. Unit conversion rules ensure that only compatible unit types can be supplied
+The [supplier part](../purchasing/supplier.md#supplier-part-pack-size) model uses real-world units to convert between supplier part quantities and internal stock quantities. The *pack quantity* of a supplier part can be specified in any unit which is compatible with the units of the base part. Refer to the [supplier part units](../part/index.md#supplier-part-units) documentation for more information.
 
 ### Parameter
 

docs/docs/part/index.md

@@ -122,10 +122,12 @@ It is possible to track parts using physical quantity values, such as *metres* o
 
 ### Supplier Part Units
 
-By default, units of measure for [supplier parts](../purchasing/supplier.md#supplier-parts) are specified in the same unit as their base part. However, supplier part units can be changed to any unit *which is compatible with the base unit*.
+A [supplier part](../purchasing/supplier.md#supplier-parts) may be sold in a different quantity or unit than is used to track the base part - for example, wire which is tracked in metres might be purchased in 100 foot reels. This is handled by the [pack quantity](../purchasing/supplier.md#supplier-part-pack-size) of the supplier part, which can be specified in any unit *which is compatible with the base unit*. The pack quantity is automatically converted into the units of the base part.
 
 !!! info "Example: Supplier Part Units"
-    If the base part has a unit of `metres` then valid units for any supplier parts would include `feet`, `cm`, `inches` (etc)
+    If the base part has a unit of `metres`, then valid pack quantities for any supplier parts would include `100 ft`, `50 cm`, `12 inches` (etc). A pack quantity of `100 ft` is equivalent to 30.48 metres.
+
+If the pack quantity is specified without units, it is assumed to be in the units of the base part.
 
 If an incompatible unit type is specified, an error will be displayed:
 

docs/docs/part/pricing.md

@@ -79,6 +79,13 @@ If the Part is designated as *purchaseable*, then historical purchase cost infor
 
 If supplier pricing information is available, this can be also used to determine price range data.
 
+Supplier price breaks are specified *per pack* of the supplier part. When calculating supplier pricing for a part, the price of each supplier price break is divided by the [pack quantity](../purchasing/supplier.md#supplier-part-pack-size) of the supplier part, so that the resulting price is expressed per unit of the base part. This allows pricing from supplier parts with different pack sizes to be compared directly.
+
+!!! info "Example"
+    If a supplier sells a part in packs of 100, at a price of $11.55 per pack, the supplier pricing for the part is $0.1155 per unit.
+
+Refer to the [supplier part pricing](../purchasing/supplier.md#supplier-part-pricing) documentation for more information.
+
 {{ image("part/pricing_supplier.png", "Supplier Pricing") }}
 
 ### BOM Pricing
@@ -118,7 +125,7 @@ Pricing calculations (and conversions) can be expensive to perform. This can mak
 
 For this reason, all information displayed in the [pricing overview](#pricing-overview) section is pre-calculated and *cached* in the database. This ensures that when it needs to be retrieved (e.g. viewing pricing for an entire BOM) it can be accessed immediately.
 
-Pricing data is cached in the [default currency](../concepts/pricing.md/#default-currency), which ensures that pricing can be compared across multiple parts in a consistent format.
+Pricing data is cached in the [default currency](../concepts/pricing.md#default-currency), which ensures that pricing can be compared across multiple parts in a consistent format.
 
 ## Pricing Updates
 

docs/docs/purchasing/supplier.md

@@ -84,11 +84,85 @@ Availability information can be manually updated via the user interface:
 
 ## Supplier Part Pack Size
 
-Supplier parts can have a pack size defined. This value is defined when creating or editing a part. By default, the pack size is 1.
+Supplier parts can have a pack size defined, using the *Pack Quantity* field. This value is defined when creating or editing a supplier part. If left blank, the pack size is 1 - each item purchased from the supplier is a single unit of the base part.
 
-When buying parts, they are bought in packs. This is taken into account in Purchase Orders: if a supplier part with a pack size of 5 is bought in a quantity of 4, 20 parts will be added to stock when the parts are received.
+The pack quantity describes how much of the base part is contained in a single pack, as sold by the supplier. For example:
 
-When adding stock manually, the supplier part can be added in packs or in individual parts. This is to allow the addition of items in opened packages. Set the flag "Use pack size" (`use_pack_size` in the API) to True in order to add parts in packs.
+| Base Part | Base Part Units | Supplier Sells | Pack Quantity |
+| --- | --- | --- | --- |
+| Screw | *(none)* | Bag of 100 screws | `100` |
+| Wire | metres | 100 foot reel | `100 ft` |
+| Paint | litres | 250 millilitre tin | `250 ml` |
+
+### Pack Quantity Units
+
+If the base part has a [unit of measure](../part/index.md#units-of-measure), the pack quantity can be specified in any *compatible* unit. The value is automatically converted into the units of the base part - in the examples above, a `100 ft` reel is equivalent to 30.48 metres of wire, and a `250 ml` tin is equivalent to 0.25 litres of paint.
+
+If no units are provided, the pack quantity is assumed to be in the same units as the base part. If the base part does not have a unit of measure, the pack quantity must be a plain number.
+
+The pack quantity must be greater than zero. An incompatible unit (e.g. specifying `250 ml` for a part tracked in metres) will result in an error.
+
+!!! info "Read More"
+    Read more about [supplier part units](../part/index.md#supplier-part-units) and [physical units of measure](../concepts/units.md)
+
+### Quantities are Counted in Packs
+
+When dealing with a supplier part, quantities are counted in *packs*, and prices are specified *per pack*. This matches how the supplier sells the item, and applies to:
+
+- [Supplier price breaks](#supplier-part-pricing) - the quantity is the number of packs, and the price is the cost of a single pack
+- [Purchase order](./purchase_order.md) line items - the quantity is the number of packs ordered, and the purchase price is the cost of a single pack
+
+InvenTree converts these values into the units of the base part where required:
+
+- When a purchase order line item is received, the quantity added to stock is the number of packs multiplied by the pack quantity. The purchase price recorded against the new stock item is the pack price divided by the pack quantity, i.e. the price per unit of the base part.
+- When calculating [part pricing](../part/pricing.md), supplier price breaks and purchase history are divided by the pack quantity, so that prices from supplier parts with different pack sizes can be compared directly.
+
+### Adding Stock Manually
+
+When adding stock manually against a supplier part which has a pack size other than 1, the quantity can be specified in packs or in base part units. This is to allow the addition of items in opened packages.
+
+Set the flag "Use pack size" (`use_pack_size` in the API) to True in order to add parts in packs. In this case, both the quantity *and* the purchase price are treated as values per pack, and converted to base part units when the stock item is created. If the flag is False, the quantity and purchase price are used as provided.
+
+!!! warning "API Usage"
+    When creating a stock item via the API against a supplier part with a pack size other than 1, the `use_pack_size` flag must be provided - otherwise the request will be rejected.
+
+### Example
+
+Consider a *Blue Paint* part, which is tracked in `litres`. A supplier sells this paint in 250ml tins, so the supplier part has a pack quantity of `250 ml`.
+
+The supplier offers a price of €8.50 per tin, when buying 10 or more tins. This is entered as a supplier price break with a quantity of `10` and a price of `€8.50`.
+
+- The price per litre of paint is €8.50 / 0.25 = €34.00, which is displayed in the *Unit Price* column of the supplier pricing table, and used for [part pricing](../part/pricing.md#supplier-pricing) calculations.
+- A purchase order line for this supplier part, with a quantity of `12` and a purchase price of `€8.50`, represents twelve tins at €8.50 each.
+- When the line item is received, 3 litres of paint are added to stock (12 x 0.25), with a purchase price of €34.00 per litre.
 
 !!! tip "Bundled Items"
     A pack size only ever represents multiple units of the *same* part. If a supplier instead sells a kit or assortment of *different* components as a single purchasable item, refer to the [bundled items](./purchase_order.md#bundled-items) documentation instead.
+
+## Supplier Part Pricing
+
+Pricing information for a supplier part is specified as a set of *price breaks*, which are displayed on the <span class="badge inventree nav side">{{ icon("currency-dollar") }} Supplier Pricing</span> tab of the supplier part detail page:
+
+{{ image("purchasing/supplier_price_breaks.png", "Supplier price breaks") }}
+
+Each price break defines the price of the supplier part when purchasing at least the specified quantity. The table displays:
+
+| Column | Description |
+| --- | --- |
+| Quantity | The minimum number of packs which must be purchased for this price break to apply |
+| Supplier Price | The price of a single pack, as entered |
+| Unit Price | The price per unit of the base part (the supplier price divided by the [pack quantity](#supplier-part-pack-size)) |
+
+### Add Price Break
+
+To add a new price break, click on the <span class="badge inventree add">{{ icon("plus-circle") }}</span> button above the pricing table. If the supplier part has a pack size other than 1, the form displays a reminder of the pack size, and how the quantity and price values are interpreted:
+
+{{ image("purchasing/supplier_price_break_form.png", "Add supplier price break") }}
+
+!!! warning "Price Per Pack"
+    The price entered for a supplier price break is the price of a *single pack* - not the total price for the specified quantity, and not the price for a single unit of the base part.
+
+Supplier price breaks are used to:
+
+- Suggest a purchase price when adding a supplier part to a [purchase order](./purchase_order.md)
+- Calculate [supplier pricing](../part/pricing.md#supplier-pricing) for the base part