Skip to main content

Pricing Classes

The suma-elementor theme contains a dedicated set of PHP classes for managing precious metals pricing logic. These classes handle spot price integration, per-product premium calculations, volume tier pricing, price update batching, and sale management.

Class Overview​

ClassNamespaceFileResponsibility
Pricing\Suma\Pricinginc/class-pricing.phpGlobal pricing manager; spot price access
PricingTools\Suma\PricingToolsinc/class-pricing-tools.phpMath utilities for pricing
Trends\Suma\Trendsinc/class-trends.phpHistorical spot price data
Product\Pricing\Suma\Product\Pricinginc/product/class-pricing.phpPer-product price calculation
Product\MetalPricing\Suma\Product\MetalPricinginc/product/class-metal-pricing.phpMetal weight × spot price calculations
Product\PriceUpdater\Suma\Product\PriceUpdaterinc/product/class-price-updater.phpBatch price update from API payload

\Suma\Pricing — Global Pricing Manager​

This class is the top-level interface for accessing current spot prices and applying them to the WooCommerce product catalog.

Key Methods​

/**
 * Get the current spot price for a metal type.
 *
 * @param string $metal_type 'gold' | 'silver' | 'platinum' | 'palladium'
 * @return float Current spot price in USD per troy ounce
 */
public function get_spot_price( string $metal_type ) : float;

/**
 * Get all current spot prices.
 *
 * @return array<string, float> ['gold' => 1850.50, 'silver' => 22.45, ...]
 */
public function get_all_spot_prices() : array;

/**
 * Update spot price cache from the API payload.
 *
 * @param array $prices Spot prices from NFusion via Laravel middleware
 * @return void
 */
public function update_spot_prices( array $prices ) : void;

Spot prices are cached in Redis (suma_pricing_cache transient) to reduce database reads on every product page load.

\Suma\Product\Pricing — Per-Product Price Calculation​

Calculates the final selling price for a specific WooCommerce product based on:

  1. Spot price (current metal market price in USD/troy oz)
  2. Metal weight (product's troy ounce content)
  3. Premium (markup over spot price as percentage or fixed dollar amount)
  4. Customer tier (retail, dealer, wholesale — different premium rates)
  5. Volume discount (volume pricing tiers, if configured)

Price Formula​

Final Price = (Spot Price × Metal Weight × Purity) + Premium

Where:

  • Spot Price = current market price from NFusion (USD per troy oz)
  • Metal Weight = _metal_weight_troy_oz product meta
  • Purity = _metal_purity product meta (e.g., 0.999 for .999 fine silver)
  • Premium = dollar amount or percentage from _premium_type and _premium_value metas

Volume Pricing​

Products with volume tiers store tiers in _volume_pricing product meta as JSON:

[
  { "min_qty": 1,   "max_qty": 19,  "premium": 3.50 },
  { "min_qty": 20,  "max_qty": 99,  "premium": 2.75 },
  { "min_qty": 100, "max_qty": null, "premium": 2.00 }
]

The PricingTools class provides the volume tier selection logic.

\Suma\Product\MetalPricing — Metal Weight Calculations​

Handles the math for calculating how much metal content a product contains.

/**
 * Calculate the metal value component of a product price.
 *
 * @param int   $product_id   WooCommerce product ID
 * @param float $spot_price   Current spot price for the metal type
 * @return float Metal value in USD
 */
public function calculate_metal_value( int $product_id, float $spot_price ) : float;

Used by Product\Pricing to get the base metal value before adding the premium.

\Suma\Product\PriceUpdater — Batch Price Updates​

Handles bulk price updates when the price update REST endpoint receives a payload from the Laravel pricing middleware.

Update Process​

1. REST API receives POST /wp-json/suma/v1/product/update-prices
2. Endpoint passes payload to PriceUpdater::update_batch()
3. For each product in payload:
   a. Look up WC product by SKU
   b. Calculate new price using Product\Pricing::calculate()
   c. Update product's _price, _regular_price in WP database
   d. Flush Redis object cache for that product
4. Return count of updated/skipped/errored products
5. CloudFront cache invalidation triggered for updated product URLs

Performance Rules​

Critical Performance Path

The price update endpoint is called every minute by the Laravel middleware. These rules must be followed:

  • No blocking external API calls inside the update loop
  • No sending emails during batch update
  • Batch operations using wp_defer_term_counting() to prevent lock contention
  • Minimize individual update_post_meta() calls; use wp_update_post() where possible

\Suma\Trends — Historical Pricing Data​

Provides historical spot price data for the NFusion live price chart widget and trend displays on the site.

/**
 * Get historical spot prices for charting.
 *
 * @param string $metal  Metal type ('gold', 'silver', 'platinum', 'palladium')
 * @param string $period Period ('1day', '1week', '1month', '3month', '1year')
 * @return array Price data points [{timestamp, price}, ...]
 */
public function get_trend_data( string $metal, string $period ) : array;

Data is fetched from NFusion and cached in Redis for the appropriate period.

Product Meta Fields (ACF)​

Meta KeyTypeDescription
_metal_typeStringgold, silver, platinum, palladium, other
_metal_weight_troy_ozFloatTroy ounce content (e.g., 1.0, 0.5, 10.0)
_metal_purityFloatPurity fraction (e.g., 0.999, 0.9995, 0.9167)
_premium_typeStringpercent or fixed
_premium_valueFloatPremium amount (% or $)
_volume_pricingJSONVolume tier definitions
_pricing_rulesJSONLegacy Dynamic Pricing format (converted by tools/task-convert-volume-pricing.php)

Tools: Volume Pricing Conversion​

web/tools/task-convert-volume-pricing.php — A web-accessible admin tool that converts the WooCommerce Dynamic Pricing plugin's tier format (_pricing_rules) to the custom _volume_pricing JSON format used by the theme's pricing classes.

Usage: Navigate to /tools/task-convert-volume-pricing.php in browser (requires admin login). Processes 20 products per batch.