Product Units in Shuup

Commonly web shops sell products which are prepackaged units and their quantities are measured in pieces. However it is sometimes needed to be able to sell products in non-integral quantities, like kilograms or ounces. In Shuup, this can be handled with sales units and display units.

Each product in Shuup has a sales unit which determines how quantities of the product are represented and if non-integral quantities are allowed. However it is possible that the sales unit has an attached display unit which overrides the representation part. This allows, for example, the internal quantities to be stored in kilograms but be displayed as grams to the customer.

Product.sales_unit: Sales unit of a Product. Usually a SalesUnit object, but can also be None. This is the internal unit which is used to store the quantities, like quantities in the order lines or stock amounts. Quantities shown to the customer should not use the sales unit, but rather a display unit, see ShopProduct.display_unit and or SalesUnit.display_unit.
SalesUnit.name: Name of SalesUnit. Usually shown only in Admin when managing units or when selecting sales unit for a product.
SalesUnit.symbol: Symbol used when rendering values of the sales unit.
SalesUnit.decimals: Number of decimals to use for values in this unit.

SalesUnit.display_unit: The default display unit of the sales unit. This property returns a DisplayUnit object, which has the sales unit as its internal unit and is marked as a default, or if there is no default display unit for the sales unit, then this will return a proxy object. The proxy object has the same display unit interface and mirrors the properties of the sales unit, such as symbol and decimals.

ShopProduct.display_unit: Display unit of a shop product, a DisplayUnit object or None.
ShopProduct.unit: The unit of the shop product as UnitInterface.
ShopProduct.display_quantity_step: Quantity step of the shop product in the display unit.
ShopProduct..display_quantity_minimum: Quantity minimum of the shop product in the display unit.
DisplayUnit.name: Name of the display unit.
DisplayUnit.symbol: Symbol of the display unit, used when rendering quantity values in the display unit.
DisplayUnit.internal_unit: The SalesUnit object which acts as the internal unit for the display unit.
DisplayUnit.ratio: Ratio between the display unit and its internal unit. E.g. if internal unit is a kilogram and display unit is gram, then this should be 0.001.
DisplayUnit.decimals: Number of decimals to use when representing quantity values in the display unit.
DisplayUnit.comparison_value: Value to use for comparison purposes. E.g. if the display unit is a gram with symbol “g” and this is 100, then the unit prices should be rendered as “$5.95 per 100g”.
DisplayUnit.allow_bare_number: If this boolean is true, then values of this unit can be shown without the symbol occasionally. Usually wanted if the unit is a Piece, i.e. showing just “$5,95” in product listings rather than “$5,95 per pc.”.
DisplayUnit.default: Use this display unit as the default display unit for its internal unit. If there is several default display units for an internal unit, then its undetermined which will be used.
UnitInterface: Interface for unit related information and functionality. Bound to a single display unit and its internal unit. Can be used for rendering and converting product quantities in the display unit or in the internal unit. Or for accessing data of either unit. See the API documentation of the UnitInterface for details.