# retail.basket-total
The checkout total, from shelf prices to the amount charged, with the VAT
split an invoice or receipt needs. It invents no arithmetic: promotions are
`retail.promotion-apply`, discount sharing is `money.allocate`, VAT is
`finance.tax.remove-vat` or `finance.tax.add-vat`, and each is pinned by its
own vectors. What this function decides is the order.
## Order of operations
1. **Promotions** on the lines, best for the customer, each deal's saving
allocated back to the lines in it.
2. **Basket discount** (a coupon, a staff discount) shared across every line
in proportion to what the line costs after promotions, with
`money.allocate`, so the shares add up to the discount exactly. It may not
exceed the basket after promotions.
3. **VAT per line**, on what the line costs after both discounts, at the rate
for its category on `onDate`. Consumer prices include VAT
(`pricesIncludeVat` true), so VAT is extracted with `remove-vat`; trade
prices exclude it, so it is added with `add-vat`. Either way VAT is on the
discounted price, which is what HMRC requires for a discount given at the
time of sale (Notice 700/7): taxing the shelf price and then taking the coupon off
overcharges VAT.
4. **Delivery** is taxed the same way, at `deliveryTaxCategory`. In the UK,
delivery charged by the seller of goods follows the VAT liability of the
goods, and a basket of mixed-rate goods has to apportion it; that
apportionment is the caller's decision (pass the category that applies, or
split delivery across calls).
5. **Totals** are sums of the per-line figures, so the receipt lines always add
up to the total, and the VAT summary groups them by rate, delivery included
when it is not zero.
`total = subtotal - promotionDiscount - basketDiscount + delivery` for
VAT-inclusive prices, and `total = net + tax` always.
## Sources
- VAT on discounts: HMRC, "Business promotions (VAT Notice 700/7)", section
7.3 (on redeeming money-off coupons, VAT is accounted for "on the amount due
from the customer"):
https://www.gov.uk/guidance/business-promotions-and-vat-notice-7007
- Delivery: HMRC, "Postage, delivery and direct marketing (VAT Notice
700/24)" (delivery charged by the seller follows the goods; mixed-rate
apportionment must be fair and justifiable, with no set method):
https://www.gov.uk/guidance/vat-on-postage-delivery-and-direct-marketing-notice-70024
- Rates: `finance.tax.vat-rate`.