Skip to main content

Sale Price Overlays

The Middleware Platform supports a sale-price overlay feature that lets you define temporary discounted prices per SKU. These are applied on top of the live nFusion spot price before syncing to WooCommerce or Algolia.

How It Works​

When a tenant has supports_markup_sale_prices = true:

  1. NFusionService::getPrices() loads all on-sale products from the products table (see Product::getOnSaleProducts()).
  2. For each product, if markup_sale_price is set and > 0, a sale_ask price is calculated:
sale_ask = base_ask + (markup_sale_price × weight_in_ounces)
  1. NFusionService::transformTiers() applies that sale price to retail tiers and returns both regular and sale-aware tier values.
  2. The transformed tier prices plus sale_starts_at and sale_ends_at are passed to sync providers.
  3. WooCommerce sync writes _sale_price, _sale_price_dates_from, and _sale_price_dates_to meta.

Managing Sale Prices​

Sale prices are managed via the Products resource in the Filament admin panel.

FieldDescription
skuProduct SKU (must match nFusion and WooCommerce)
markup_sale_pricePer-ounce markup reduction (a lower number = cheaper sale price)
sale_starts_atWhen the WooCommerce sale should activate
sale_ends_atWhen the WooCommerce sale should deactivate

Base Sale Price Formula​

base_ask      = nFusion BaseAsk (spot price + base markup, before retail tier markups)
weight        = product weight in troy ounces
markup_sale   = markup_sale_price from products table

sale_ask = base_ask + (markup_sale × weight)

If markup_sale is lower than the standard markup, the sale price will be lower than the regular price.

Tier Sale Price Logic (transformTiers())​

transformTiers() now includes sale-aware tier pricing for retail tiers when all of these are true:

  • isOnSale === true (sale window is active)
  • saleAskPrice > 0
  • askPrice, baseAskPrice, and tier['Ask'] are available

For each tier:

tier_delta    = tier_ask - ask_price
sale_tier_ask = sale_ask + tier_delta

# Clamp to stay within valid bounds
sale_tier_ask = max(base_ask, min(ask_price, sale_tier_ask))

This preserves the tier discount/spread from the regular price while preventing invalid sale values.

Each transformed tier includes:

  • ask - effective price used by sync (sale tier price when on sale; regular tier price otherwise)
  • ask_regular - regular tier price (set only in sale mode)
  • ask_sale - computed sale tier price (set only in sale mode)
  • markup - tier_ask - base_ask
  • qty - tier quantity break

If no tier data is provided, transformTiers() returns null.

WooCommerce Sync Integration​

When syncing to WooCommerce:

  • _regular_price remains the regular price
  • _sale_price is set to sale_ask
  • _sale_price_dates_from is set to sale_starts_at (Unix timestamp)
  • _sale_price_dates_to is set to sale_ends_at (Unix timestamp)
  • tier pricing receives sale-aware ask, ask_regular, and ask_sale values from transformTiers()

WooCommerce uses these dates to automatically activate and deactivate the sale price on the storefront.

Scope Notes​

  • Sale tier transforms are applied to retail tiers.
  • Wholesale tiers are transformed without sale overlay parameters.
  • If supports_markup_sale_prices is disabled for a tenant, normal non-sale tier pricing is used.

Populating the Products Table​

Products are inserted or updated in the products table by the WooCommerce product-update webhook. When WooCommerce sends a product.updated event, WooCommerceProductUpdateController creates or updates a Product record.

See WooCommerce Product Update Webhook → for details.