# Supplier Purchase Pricing

## Overview

Supplier Purchase Pricing manages the supplier-specific commercial rules that default onto purchase order lines. A `PurchasePriceList` groups one supplier's purchasable pricing conditions, while `PurchasePriceRule` defines the actual pricing logic for a given item or purchasing context, such as effective date, minimum quantity, currency, and unit of measure. These rules allow procurement teams to keep negotiated purchase prices in a structured, reusable form instead of entering them manually on every order.

The feature is intentionally procurement-specific rather than generic enterprise pricing. It focuses on "what do we expect to pay this supplier for this item under these conditions?" and provides deterministic price selection when buyers create or revise purchase orders. When the supplier's purchasing unit of measure differs from the item's stocking unit, this feature relies on conversion definitions owned by `primitives` rather than re-implementing unit-conversion logic in purchase. Blanket orders and release-against-contract pricing remain explicit non-goals for the MVP.

## Business Purpose

- Reduce manual entry by defaulting supplier-negotiated prices into purchase order lines
- Capture quantity breaks, date validity, and currency-specific supplier agreements
- Preserve commercial history by snapshotting the applied rule onto the purchase order at ordering time
- Support consistent purchasing across buyers, companies, and repeated replenishment cycles
- Make price variance detection possible when supplier bills arrive above or below the agreed purchase condition
- Separate procurement pricing from product definition and from downstream AP settlement logic
- Keep purchasing-UoM pricing compatible with stock-UoM receiving by delegating conversions to the shared unit-conversion capability

## Process Flow

```mermaid
flowchart TD
    A[Create Purchase Price List] --> B[Add Purchase Price Rules]
    B --> C[Set supplier, item scope, dates, quantity breaks]
    C --> D[Activate list]
    D --> E[Buyer creates PO line]
    E --> F[Resolve applicable rules]
    F --> G{Rule found?}
    G -->|Yes| H[Apply best matching rule]
    G -->|No| I[Manual price entry]
    H --> J[Snapshot applied price and rule reference on PO line]
    I --> J
    J --> K[Order placed]
    K --> L[Supplier bill matching compares invoice price to ordered price]
```

## Scenario Patterns

- **Annual supplier contract**: A supplier price list is created for the fiscal year with negotiated base prices for each frequently purchased item
- **Quantity break pricing**: A supplier offers 10 currency per unit above 100 pieces and 9 currency per unit above 500 pieces; the applicable tier is selected automatically based on ordered quantity
- **Time-bounded promotion**: A temporary supplier discount is valid for one month. Orders placed within the effective range receive the temporary price, after which the normal rule applies again
- **Multi-currency purchasing**: The same supplier provides one item in USD and another in EUR; purchase price rules keep those commercial conditions separate and explicit
- **Supplier-specific UoM**: A supplier sells an item by carton while the item's internal base unit is piece; the purchase price rule is keyed to the purchasing UoM used on the PO
- **UoM conversion delegation**: A buyer orders in cartons while inventory receives in pieces. The purchase rule prices the carton, and purchase calls the shared unit-conversion definitions from `primitives` to derive receipt and variance comparisons consistently
- **One-time exception**: The system defaults the contracted price, but the buyer manually overrides it for a special order while retaining the original matched-rule reference for auditability
- **Rule retirement**: An old price list is deactivated when a new contract begins, preventing future orders from using obsolete supplier pricing
- **Price variance review**: The supplier invoice arrives above the ordered unit price, and the matched purchase price rule helps determine whether the variance is expected or should be blocked

## Test Cases

- Creating a purchase price list for an ACTIVE supplier with the SUPPLIER role should succeed
- A purchase price rule must require a positive unit price and a valid item or defined pricing scope
- A quantity-break rule must not allow a negative minimum quantity
- A rule with an effective end date earlier than its start date should fail validation
- Inactive price lists or inactive rules must not be selected for new purchase orders
- When multiple rules match the same PO line, rule resolution must follow deterministic precedence based on supplier, item scope, UoM, minimum quantity, date, and explicit priority
- When no rule matches a PO line, the system should allow manual pricing while marking the line as unmatched to a price rule
- Editing a price rule after a purchase order is placed must not retroactively change the ordered unit price on that existing order
- A purchase price list must be isolated by company when company-specific procurement data is required
- Duplicate rules with indistinguishable precedence for the same supplier, item, date, and quantity context should be rejected or warned
- A purchase price rule currency must reference a valid currency from the primitives module
- If a purchase price rule UoM differs from the item's stocking UoM, a valid conversion path from `primitives` must exist before the rule can be used operationally
- Only ACTIVE items should be assignable to newly created purchase price rules
- A buyer should be able to override a defaulted price on a draft order while retaining audit information about the default rule
- Supplier bill matching should be able to compare invoice price against the purchase order's snapshotted price even if the underlying rule is later deactivated
- Only authorized procurement users should be able to create, update, activate, or deactivate purchase price lists

## Reference Links

- [Odoo vendor price and blanket-order purchasing concepts](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/purchase/manage_deals.html)
- [Oracle Fusion Cloud Procurement documentation](https://docs.oracle.com/en/cloud/saas/procurement/index.html)
- [SAP S/4HANA Cloud procurement documentation](https://help.sap.com/docs/SAP_S4HANA_CLOUD)
