GoldRate Live – Gold & Jewellery Pricing for WooCommerce

Live metal-rate pricing for gold and jewellery shops, by Zaki International (engzaki.pro). Slug zi-live-gold-price · class prefix ZILGP_ · option / hook prefix zilgp_ · text domain zi-live-gold-price · PHP 7.4–8.3 · WordPress 6.0+ (tested 6.8) · WooCommerce 7.0+ (tested 9.9).

Product page: https://engzaki.pro/en/products/live-gold-price-woocommerce (suggested marketing name: GoldRate Live – Gold & Jewellery Pricing for WooCommerce).

---

1. Overview

Jewellers price by formula: weight × today's karat rate + making charge (+ stones). This plugin applies that formula inside WooCommerce:

1. You set today's rates, either by hand or automatically from an API you subscribe to (GoldAPI.io, MetalpriceAPI, Metals-API, or any JSON endpoint).
2. The plugin derives every grade from the pure (24K / 999) rate by purity, applies your markup, currency conversion and rounding, and stores a rate version.
3. Each product (or variation) has a metal, karat, weight and making charge. WooCommerce's price getters are filtered, so the shop, product pages, variation price ranges, mini-cart, cart, checkout (classic and blocks) and orders all use the live price.
4. The shopper sees a rates bar, a price breakdown, and optionally a cart price hold. The rates used are stored on the order.

If anything is missing (license, rate, weight, karat), the product's normal stored WooCommerce price is used. The plugin never prices a product at 0.

2. Requirements

WordPress	6.0 or newer (tested 6.8)
PHP	7.4 – 8.3
WooCommerce	7.0 or newer (tested 9.9), HPOS and block cart / checkout supported
Optional	An account with a rate API (GoldAPI.io, MetalpriceAPI, Metals-API or your own)
Cron	WP-Cron (a real server cron calling wp-cron.php is recommended for exact refresh times)

3. Installation

1. Plugins → Add New → Upload Plugin → zi-live-gold-price-1.0.0.zip → Activate. Two tables are created: {prefix}zilgp_rate_history and {prefix}zilgp_log.
2. Gold Rates → License: paste the EZ-… key and click Activate.
3. Gold Rates → Settings: configure the rate source (see 4.3).
4. Gold Rates → Rates (manual) or Dashboard → Fetch now (API).
5. Configure your products (see 5).
6. Place the rates bar (see 6).

4. Configuration, screen by screen

The plugin adds a top-level Gold Rates menu (capability manage_woocommerce, filterable via zilgp_capability).

4.1 Dashboard

• Current rates per gram – one card per metal / grade with ▲/▼ change versus the previous recorded day.
• Source, rate date shown to shoppers, last successful fetch, next automatic fetch, last error, rate version.
• Fetch now – calls the API immediately. If rates are locked or the last update was rejected by the spike guard, an "Accept even if locked or a big move" checkbox appears.
• Lock / Unlock rates and a link to Manual override.
• Rate history – daily line chart (inline SVG, no external library) for any grade over 30 days to 5 years. It shows low / high / change and has a Download CSV link.
• Shortcodes and blocks reference and Recent activity (last 8 log rows).

4.2 Rates

• With Manual rates as the source, enter today's selling rate for the purest grade (e.g. 24K). Empty grades are derived by purity. Fill any grade to set it explicitly.
• With an API as the source, the same table works as overrides. A filled grade replaces the API value as-is, without markup. "Remove all overrides" clears them.
• Lock rates – while locked, the cron skips API updates. Manual edits still apply.

4.3 Settings

Rate source

Field	Notes
Source	Manual, GoldAPI.io, MetalpriceAPI, Metals-API, Custom JSON API
API key	Stored in the zilgp_settings option, shown masked, never logged. A request is made only for the selected provider.
API currency	Empty = the WooCommerce store currency (recommended). Otherwise e.g. USD.
Conversion rate	Multiplier from the API currency to the store currency (e.g. 3.6725 USD → AED). Keep 1 when the API returns your store currency.
Custom API	URL with {key} / {currency} placeholders, optional key header name, JSON path per metal (rates.XAU, data.items[0].price), unit (troy ounce / gram / kilogram), "invert" for "metal per 1 currency unit" answers.
Refresh	15 min, 30 min, 1 h, 3 h, 6 h, twice a day, daily. The page estimates monthly API calls.
Spike guard	Default 15 %. An automatic update that moves a metal more than this since the last update is not applied, and a warning is logged. 0 = off.
Warn when older than	Default 26 h. Admin notice when the last successful fetch is older.
Lock rates	Same switch as on the Rates page.

Provider endpoints used:

Provider	Request	Parsed
GoldAPI.io	GET https://www.goldapi.io/api/{XAU,XAG,XPT}/{CUR} with header x-access-token (one call per metal)	price_gram_24k, else price / 31.1034768
MetalpriceAPI	GET https://api.metalpriceapi.com/v1/latest?api_key=…&base={CUR}&currencies=XAU,XAG,XPT	rates.{CUR}XAU, else 1 / rates.XAU, ÷ 31.1034768
Metals-API	GET https://metals-api.com/api/latest?access_key=…&base={CUR}&symbols=XAU,XAG,XPT	same as above

Calculation

• Metals – gold is always on. Silver and platinum are optional.
• Grades and purity per metal – one per line, label = purity (0.916 or 916). Defaults: 24K 1, 22K 0.916, 21K 0.875, 18K 0.75, 14K 0.585 · Silver 999 1, 925 0.925 · Platinum Pt 999 1, Pt 950 0.95. Up to 12 grades per metal.
• Markup on spot per metal (API rates only).
• Round rates to (default 0.01) and Round product prices to (default 1) with direction nearest / up / down.

Formula: rate(grade) = round( spot_per_gram × fx × (1 + markup/100) × purity ), unless a manual value is set for that grade.

Storefront

• Price breakdown on product pages, shop grid note (21K · 12.7 g × rate/g), rate time, top bar plus its grades (gold:24k,gold:22k,…).
• Pay in instalments line: number of payments (0 = off) and an optional text with {n} and {amount}. This line is for display only and does not take payments.
• Default note under the breakdown (e.g. a VAT note).

Checkout and catalogue

• Hold price in cart (minutes, 0 = off) – see 7.
• Order e-mails – add the "Metal rates applied to this order" block.
• Sorting and price filter – keep wc_product_meta_lookup.min_price / max_price in line with live prices (background batches after every rate change and after product saves).
• Keep logs (days), Uninstall (delete all data), Update server.
• A Refresh catalogue sort prices now button.

4.4 Logs

Filter by level (info / warning / error), paginated, with a "Clear log" button. Events include fetched, fetch_failed, spike_rejected, locked, manual_saved, settings and license. API keys and license keys are stripped before anything is written.

4.5 License

Paste the key and click Activate. You can also Check now or Deactivate on this site (this frees the domain on engzaki.pro). The page shows the status, domain, expiry and "updates until".

Without a valid license (or grace period):

• Dynamic pricing, automatic API refresh, the cart hold and order snapshots are off. Products sell at their stored price.
• Settings, manual rates, the rates bar / block / widget and the dashboard keep working.
• An admin notice explains this and links to the license page and the product page. On non-plugin screens it can be hidden for 14 days.

Licensing contract: POST https://engzaki.pro/api/license/validate {key, domain, product:"zi-live-gold-price"}. The result is cached for 12 h, and if engzaki.pro can't be reached, the last valid state is kept for a 7-day grace period. Updates come from POST https://engzaki.pro/api/plugins/zi-live-gold-price/update through the standard WordPress update screens. The owner can force-enable dynamic pricing with add_filter( 'zilgp_is_licensed', '__return_true' );.

5. Products

Product data → Metal pricing tab (simple and variable products):

Field	Meta key	Notes
Price by metal rate	_zilgp_enabled	yes / no
Metal and karat	_zilgp_metal, _zilgp_grade	The dropdown lists every enabled grade with its current rate
Weight (g)	_zilgp_weight	Net metal weight
Making charge type	_zilgp_making_type	per_gram, fixed, percent (of metal value)
Making charge	_zilgp_making	Amount or %
Stones / extras	_zilgp_extra	Fixed amount added
Making discount (%)	_zilgp_discount	Optional. Discounts only the making charge and is shown as a sale price
Note under the breakdown	_zilgp_note	Empty = default note

price = round( weight × rate + making + extras ). With a discount, sale = round( weight × rate + making × (1 − d) + extras ).

• A Price now preview shows the live result.
• Keep a normal Regular price in the General tab as the fallback. If it is empty when you save, it is filled with the computed price.
• While a product is metal-priced and licensed, any stored WooCommerce sale price is ignored. Use the making discount instead.

Variations – each variation has karat, weight, making type, making and extras fields. Empty fields inherit from the product. Use the normal price for this variation (_zilgp_exclude) opts a variation out. Variations need the product-level switch to be on.

Bulk edit (Products → select → Edit) – metal pricing on / off, karat, making type, making, extras, discount.

Products list – a "Metal" column (21K · 12.7 g).

CSV – WooCommerce's product importer / exporter gets these columns (header text or column id both map automatically): zilgp_enabled (yes/no), zilgp_metal (gold/silver/platinum), zilgp_grade (key like 21k or label like 21K), zilgp_weight, zilgp_making_type, zilgp_making, zilgp_extra, zilgp_discount, zilgp_note.

6. Storefront output

Output	How
Rates bar / cards / table / ticker	[zi_gold_rates layout="bar|cards|table|ticker" grades="gold:24k,gold:22k,gold:21k,gold:18k" title="" show_date="yes" show_change="yes"] (karats= works as an alias; empty grades = all enabled)
One rate inline	[zi_gold_rate metal="gold" grade="22k"]
Price breakdown anywhere	[zi_gold_breakdown id="123"] (default: current product)
Block	Metal rates (dynamic, server-rendered; layout, title, grades, update time, change toggles)
Widget	Metal rates (Zi Live Gold Price)
Top bar	Settings → Storefront → Top bar (wp_body_open)
Product page	Breakdown under the price (priority 11 on woocommerce_single_product_summary). For variable products it updates per selected variation.
Shop grid	Note under the price plus the optional "Pay in N" line

The ticker pauses on hover, scrolls in the right direction in RTL, and becomes static under prefers-reduced-motion. Styling uses CSS variables (--zilgp-gold, --zilgp-line, --zilgp-up, --zilgp-down, --zilgp-radius) that themes can override.

7. Cart hold and order snapshot

• Hold: when a metal-priced item is added to the cart, its breakdown is stored in the WooCommerce session with a held_until time. Until then, the price getters return the held price for that shopper. When it expires, the item is re-priced at the current rate, a new hold starts, and the shopper sees a notice if the price changed. The cart line shows "Price held until …".
• Order: every line stores _zilgp (metal, grade, weight, rate, metal value, making, extras, total, rate time, rate version). The order stores _zilgp_rates (the full rate table, rate date, version, source). Both are written through the WooCommerce CRUD API, so they work with HPOS. The line breakdown shows as "Metal price" in admin, e-mails, My Account and most invoice plugins that print item meta. The order-level block appears in e-mails and on the thank-you / view-order pages.

8. How it works (developers)

• ZILGP_Rates – zilgp_rates option (version, spot, rates, timestamps), zilgp_manual option, derivation, daily history upsert (INSERT … ON DUPLICATE KEY UPDATE, keeps high / low).
• ZILGP_Sources – provider requests and parsing.
• ZILGP_Pricing – filters woocommerce_product_get_price|regular_price|sale_price, the …variation_get_… equivalents, and woocommerce_variation_prices_* (priority 5, filter zilgp_price_filter_priority). It adds the rate version to woocommerce_get_variation_prices_hash. Breakdowns are memoised per request and in the object cache, keyed by product, rate version and a salt that changes on product saves.
• Cron: zilgp_refresh_rates (your interval), zilgp_daily (log prune, license recheck, history row), zilgp_sync_prices (lookup-table batches), zilgp_license_recheck.

Hooks:

Hook	Type	Use
zilgp_is_licensed	filter	Force-enable on your own sites
zilgp_capability	filter	Admin capability
zilgp_rate	filter	Adjust a single rate at read time
zilgp_computed_rates	filter	Adjust the full derived table
zilgp_fetched_spot	filter	Adjust / replace provider results (per gram, API currency)
zilgp_product_config	filter	Change a product's pricing inputs
zilgp_breakdown	filter	Change the computed breakdown
zilgp_breakdown_html, zilgp_rates_html	filter	Markup
zilgp_display_amount	filter	Display-currency conversion for breakdown / rates
zilgp_rates_changed	action	Purge page cache, notify, etc.
zilgp_sync_batch_size	filter	Lookup sync batch size (default 50)
zilgp_license_api_url, zilgp_update_url	filter	Staging servers

Multilingual / multi-currency – wpml-config.xml and pll_copy_post_metas copy the pricing fields to translations. vat_note and pay_in_label are registered with WPML String Translation / Polylang. Breakdown and rate amounts pass through wcml_raw_price_amount when WooCommerce Multilingual is active. Product prices are produced in the store's base currency at priority 5, so currency switchers that hook the same getters later can convert them. Test your specific switcher.

9. Troubleshooting

Symptom	Check
Prices did not change	License active? Product has "Price by metal rate", a karat and a weight > 0? A rate exists for that karat (Dashboard)? Page cache?
Product shows its old price	That is the fallback: no license, no rate, or missing weight / karat.
"Rates are out of date"	Dashboard → Last error. Then check the API key and quota, test with Fetch now, and make sure WP-Cron runs (DISABLE_WP_CRON + server cron).
"moved xx% … not applied"	Spike guard. Usually a wrong currency or conversion. Fix it, then use Fetch now with "accept".
Rates look 31× too high or low	Custom API unit (ounce vs gram) or the "invert" setting.
HTTP 401 / 403 from the API	Wrong key or plan limits. The message from the provider is shown (with the key removed).
Sort by price is wrong	Settings → "Sorting and price filter" on, then Refresh catalogue sort prices now. Make sure WP-Cron runs.
Variation price range not updating	It refreshes on each rate-version change. Clear transients if a caching plugin stores them persistently.
Top bar not visible	Your theme must call wp_body_open(). Use the shortcode or block instead.

Logs: Gold Rates → Logs.

10. FAQ

Which currency does the API use? Your store currency, unless you set another one plus a conversion rate.

Is the making charge taxed? The total price goes to WooCommerce, and tax follows your WooCommerce tax settings. The plugin doesn't decide tax treatment. Confirm VAT handling for gold (e.g. investment gold vs jewellery) with your accountant.

Can I show rates without selling online? Yes. The rates bar / block / widget work with manual rates even without a license.

Can different products use different markups? Use the making charge for per-product margins. Markup is per metal.

Does it support 22K with 0.917 or 0.920? Yes. Edit the purity lines in Settings.

What happens on uninstall? By default all data is kept. If "Delete all plugin data" is ticked, the plugin's options, tables and product pricing fields are deleted. Order snapshots stay with your orders.

11. Development

• tests/smoke.php – stub-based smoke test (rounding, derivation, providers, pricing, spike guard, license). Run with php tests/smoke.php.
• tools/i18n.py pot | po ar | mo – builds languages/zi-live-gold-price.pot, -ar.po, -ar.mo from tools/tr_ar.json.
• tools/build.py – builds ../zi-live-gold-price-<version>.zip (excludes tests/ and tools/).