Skip to content
Bullion API

Set up the WooCommerce metal-cost plugin

Install the plugin, connect your Bullion API key, save weight, purity and markups on each product, and read the estimate. Every step, and what to do when one fails.

The plugin shows metal value estimates. It never changes your product prices. Regular prices, sale prices, carts and checkout prices stay exactly as you set them.

Early access. Gold and silver in GBP, on simple products in the classic WooCommerce product editor. The estimate is visible to shop administrators only.

What you will see

Synthetic example: a 10 g gold ring at 750 fineness (18ct), a 20% markup and a £15 fixed addition, priced at £80 per gram.

Worked estimate, step by step
StepWorkingResult
Metal value£80.00 × 10 g × 750 ÷ 1000£600.00
With markup£600.00 + 20%£720.00
Estimate£720.00 + £15.00£735.00

The selling price is whatever you entered in the product's own price fields.

Before you start

  • A WordPress 7.1 site with WooCommerce active. The tested baseline is WordPress 7.1.3, WooCommerce 11.2.1 and PHP 8.3 on a 64-bit system. PHP 8.1 or later is declared.
  • The PHP Sodium extension, if you want to save the key on the settings page. Without it, set the key in wp-config.php instead (see step 2).
  • A Bullion API key from your dashboard. The key's owner must have verified their email address, or price requests are refused.
  • A staging copy of your shop to try it on first.

1. Install and activate

  1. Ask us for the plugin ZIP. During early access it is sent on request, and no API key is included in it.
  2. In WordPress, open Plugins → Add Plugin → Upload Plugin, choose the ZIP and select Install Now.
  3. Select Activate. Keep only one copy of the plugin active; deactivate any earlier copy first.
  4. Open an existing simple product. Metal-cost calculator appears above Product data. It works at once in a clearly labelled synthetic mode, with no key, so you can try the screens before connecting anything.

2. Add your API key

  1. Open WooCommerce → Bullion API connection as an administrator.
  2. Set Price source to Bullion API and paste your key into New API key, then save. The field always comes back empty; leave it blank later to keep the saved key. Until you add yours, the placeholder is bullion_YOUR_API_KEY.
  3. Open a product and select Refresh from Bullion API. A price and its observation time appear when the connection works.

The key is encrypted with Sodium and stored in a WordPress option. Only your WordPress server contacts Bullion API, over HTTPS, sending the key in the X-API-Key header. It is never sent to a shopper's browser.

3. Set weight, purity and markups per product

Edit a simple product, fill in the Metal-cost calculator panel and select the product's Update button. Update saves the calculator inputs. Preview estimate does not.

Calculator fields and their limits
FieldWhat to enter
MetalGold or silver.
Weight and unitGrams, kilograms or troy ounces. Above 0 and up to 100, with up to three decimals.
FinenessParts per thousand, from 1 to 1000. 750 is 18ct gold; 925 is sterling silver.
Percentage markup0 to 1000, with up to two decimals. Applied to the metal value.
Fixed addition£0 to £1,000,000, with up to two decimals. Added last.

If a value is invalid, the product keeps its previous complete set of calculator inputs and shows a message. A very precise combination that is too large to calculate exactly is refused rather than rounded; reduce the weight, the markup or the decimals.

4. Read the estimate

Select Preview estimate in the panel. The estimate is the price per gram × the weight in grams × fineness ÷ 1000, plus the percentage markup on that metal value, then the fixed addition. It is shown to two decimals and rounded half up.

Next to it you see the observation time, which is when that price was taken, and a separate refresh time, which is when the plugin last fetched it. The two can differ.

An observation older than six hours is flagged as out of date, but the estimate still uses it. If no price has ever been saved, there is no estimate; the plugin does not invent one.

5. Turn on scheduled refresh

Background refresh is off on a new installation. To turn it on, return to WooCommerce → Bullion API connection, tick Hourly background refresh, choose gold, silver or both, and save. It needs Bullion API as the price source and a saved key. The first run follows about a minute later.

  1. The plugin asks once an hour

    A WordPress scheduled task runs hourly, at most one successful request per metal per hour. Gold and silver together use up to about 1,440 requests a month.

  2. Prices refresh hourly on weekdays

    Bullion API stores a new observation each hour on weekdays. At the weekend it refreshes much less often, but the plugin still asks every hour and gets the newest stored observation, so the price and its observation time often come back unchanged. The six-hour warning can show then; it is expected.

  3. A failed run keeps the last good price

    The saved price and its timestamps are untouched, the failure is recorded in the status view, and the plugin backs off before it tries again. Your selling prices are not touched either way.

The status view shows when background refresh is on, the next run, the last completed run, what happened for each metal, and whether a run is overdue. Times use your site's timezone.

Make sure your host runs it

The plugin schedules the task; WordPress cron runs it, and it only runs when your site gets visits. On a quiet site, or where DISABLE_WP_CRON is true, set up a server runner: check that bullion_api_hourly_refresh is due, and if so run wp cron event run bullion_api_hourly_refresh. Do not run that command more often than hourly without that check. To force refresh on or off from the server, use the BULLION_API_BACKGROUND_REFRESH constant shown in step 2.

Check the connection from a terminal

The plugin makes this request for each metal. The first line reads your key into BULLION_KEY without showing it, so the key stays out of each command and your shell history. Never paste a real key into a page, a ticket or a shared file.

read -rs BULLION_KEY && export BULLION_KEY   # paste your key, then press Enter

curl "https://api.bullionapi.dev/v1/gold/price?currency=GBP&unit=gram" \
  -H "X-API-Key: $BULLION_KEY"

curl "https://api.bullionapi.dev/v1/silver/price?currency=GBP&unit=gram" \
  -H "X-API-Key: $BULLION_KEY"

A trimmed response looks like this. The price is a decimal string, never a number:

{
  "status": "success",
  "metric": "price",
  "metal": "gold",
  "currency": "GBP",
  "unit": "gram",
  "series": [
    {
      "id": "gold_price",
      "unit": "gram",
      "frequency": "hourly",
      "method": "latest",
      "observations": [{ "date": "<UTC timestamp>", "value": "<decimal string>" }]
    }
  ]
}

If you read the price in your own code, keep it as text or a decimal type and round only when you show it, to two decimals. The plugin does the same. On the command line, jq -r prints the string untouched:

curl -s "https://api.bullionapi.dev/v1/gold/price?currency=GBP&unit=gram" \
  -H "X-API-Key: $BULLION_KEY" \
  | jq -r '.series[0].observations[0].value'

When something goes wrong

The plugin shows a short message in the product editor and the status view. None of these change a product price, and a failed refresh keeps the last good price.

Errors, what the plugin shows and what to do
StatusCodeWhat the plugin saysWhat to do
401missing_api_key or invalid_api_keyAPI key was rejected.Enter the key again under Bullion API connection, or check the wp-config.php value. Check the key has not been revoked.
403email_not_verified or trial_endedAccess was denied.Verify the key owner's email address, or choose a paid plan if the free trial has ended.
404no_data or not_foundNo GBP price is currently available.Try again after the next hourly run. If it persists, contact support.
429rate_limited or quota_exceededQuota or rate limit reached.Wait for the next run. For quota_exceeded, check your plan on the pricing page.

Network failures, timeouts and unexpected responses are reported the same way, and an empty store of prices says so rather than showing an estimate. An error body from the API has this form:

{
  "status": "error",
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

Plans and use in your shop

The free trial lasts 14 days with 1,000 requests, and is for evaluation, not for a shop that is trading. Using prices in your own business needs a paid plan; every paid plan includes commercial use. Compare plans on the pricing page and read the usage terms.

With hourly refresh on for both metals, the plugin makes up to about 1,440 requests a month, so check your plan's allowance.

Need more than estimates?

Use the API directly in your application.

Read the API documentation