apskel-pos-backend/PRODUCT_VARIANT_PRICE_MODIFIER.md

Product Variant Price Modifier Implementation

Overview

This document describes the implementation of price modifier functionality for product variants in the order processing system.

Feature Description

When a product variant is specified in an order item, the system now automatically applies the variant's price modifier to the base product price. This allows for flexible pricing based on product variations (e.g., size upgrades, add-ons, etc.).

Implementation Details

1. Order Processor Changes

The OrderProcessorImpl has been updated to:

• Accept a ProductVariantRepository dependency
• Fetch product variant information when ProductVariantID is provided
• Apply the price modifier to the base product price
• Use variant-specific cost if available

2. Price Calculation Logic

// Base price from product
unitPrice := product.Price
unitCost := product.Cost

// Apply variant price modifier if specified
if itemReq.ProductVariantID != nil {
    variant, err := p.productVariantRepo.GetByID(ctx, *itemReq.ProductVariantID)
    if err != nil {
        return nil, fmt.Errorf("product variant not found: %w", err)
    }
    
    // Verify variant belongs to the product
    if variant.ProductID != itemReq.ProductID {
        return nil, fmt.Errorf("product variant does not belong to the specified product")
    }
    
    // Apply price modifier
    unitPrice += variant.PriceModifier
    
    // Use variant cost if available, otherwise use product cost
    if variant.Cost > 0 {
        unitCost = variant.Cost
    }
}

3. Database Schema

The product_variants table includes:

• price_modifier: Decimal field for price adjustments (+/- values)
• cost: Optional variant-specific cost
• product_id: Foreign key to products table

4. API Usage

When creating orders or adding items to existing orders, you can specify a product variant:

{
  "order_items": [
    {
      "product_id": "uuid-of-product",
      "product_variant_id": "uuid-of-variant",
      "quantity": 2,
      "notes": "Extra large size"
    }
  ]
}

5. Example Scenarios

Scenario 1: Size Upgrade

• Base product: Coffee ($3.00)
• Variant: Large (+$1.00 modifier)
• Final price: $4.00

Scenario 2: Add-on

• Base product: Pizza ($12.00)
• Variant: Extra cheese (+$2.50 modifier)
• Final price: $14.50

Scenario 3: Discount

• Base product: Sandwich ($8.00)
• Variant: Student discount (-$1.00 modifier)
• Final price: $7.00

Validation

The system includes several validation checks:

1. Variant Existence: Verifies the product variant exists
2. Product Association: Ensures the variant belongs to the specified product
3. Price Integrity: Maintains positive pricing (base price + modifier must be >= 0)

Error Handling

Common error scenarios:

• product variant not found: When an invalid variant ID is provided
• product variant does not belong to the specified product: When variant-product mismatch occurs

Testing

The implementation includes unit tests to verify:

• Correct price calculation with variants
• Proper error handling for invalid variants
• Cost calculation using variant-specific costs

Migration

The feature uses existing database schema from migration 000013_add_cost_to_product_variants.up.sql which adds the cost column to the product_variants table.

Future Enhancements

Potential improvements:

1. Percentage-based modifiers: Support for percentage-based price adjustments
2. Conditional modifiers: Modifiers that apply based on order context
3. Bulk variant pricing: Tools for managing variant pricing across products
4. Pricing history: Track price modifier changes over time