How to Add Live Gold Prices to Your Jewelry Website

Most customers check the gold price on their phone before they reach your counter. The number they see is almost always the spot price for one troy ounce of pure gold. The ring in their hand is 14K, weighs a few grams, and nobody has shown them how to get from one number to the other. That gap is where trust is won or lost.

A gold price API closes the gap automatically. Instead of someone updating a price board by hand, your website asks for current prices, receives per-gram values for every karat, and shows them with a clear "as of" time. This guide covers the math, the units customers expect, responsible display, key safety, and caching. The code examples use the Karatology Metal Price API, but the principles apply to any price source.

Why Live Per-Gram Karat Prices Matter for Jewelers

Spot price is a benchmark for pure metal traded in bulk. Your customers buy 14K chains, sell broken 10K earrings, and compare 18K and 22K bangles. A per-gram price for each karat speaks their language.

• Customers think in grams and karats. A board that reads "14K: $75.01 per gram" answers the question they actually have.
• Consistency builds trust. When the website, the buy counter, and the sales floor use the same formula, staff spend less time defending numbers.
• Manual boards go stale. Gold can move meaningfully within a single day. A figure typed in at 9 AM may be wrong by the afternoon.
• Transparent buying wins sellers. Buyers who show melt value per gram, and the percentage they pay, look more credible than shops that quote one unexplained number.

If you want the background on karat systems first, our gold karat chart covers every purity from 8K to 24K.

The Math: From Spot Price to Karat Price Per Gram

Every karat price comes from three numbers: the spot price per troy ounce, the number of grams in a troy ounce (31.1035), and the purity of the alloy.

Karat price per gram = (spot price per troy ounce / 31.1035) x purity

Purity for a karat is simply the karat divided by 24. 14K is 14 / 24, or 0.5833 when rounded to four decimals.

Worked Example: 14K at $4,000.00 an Ounce

The spot price below is an illustrative round number, not a current quote.

1. Pure gold per gram: $4,000.00 / 31.1035 = $128.6029
2. 14K purity: 14 / 24 = 0.5833
3. 14K value per gram: $128.6029 x 0.5833 = $75.0141, displayed as $75.01
4. A 7.2 gram 14K chain: 7.2 x $75.0141 = $540.10 in gold content

If your buy counter pays 85% of melt value, the payout on that chain is $540.10 x 0.85 = $459.09. The /v1/melt endpoint does this in one call when you pass payout=85.

Karat Value Table at an Illustrative Spot Price

This table applies the formula at $4,000.00 per troy ounce to the karats jewelers handle most often.

Two details in this table trip up a lot of pricing pages.

First, 24K is calculated at 0.999, not 1.000. Commercially pure gold is sold as 999 or 999.9 fine, so pricing 24K at a perfect 1.000 slightly overstates its value.

Second, 14K and the 585 stamp are not quite the same number. Mathematically, 14K is 0.5833 pure. A 585 hallmark states a minimum of 0.585. At $4,000.00 spot, that difference is about $0.22 per gram, or $10.93 on a 50 gram lot. Our guides to 585 gold and 750 gold explain where each convention comes from.

Choosing Units: Grams, Pennyweight, or Tola

The right unit depends on who reads your page. The wrong one forces mental conversions, which invite mistakes and suspicion.

For most retail sites, grams should be the default. If trade customers bring scrap in pennyweight, show both. If your customers buy 22K jewelry by the tola, price in tola. Switching is one query parameter: unit=g, unit=dwt, or unit=tola.

Freshness: Live Calls, Hourly Prices, Honest Timestamps

Freshness is where many price widgets overpromise. With the Karatology Metal Price API, every call fetches current prices at request time. The underlying source collects new prices hourly, so a response reflects the most recent hourly collection. Every response tells you exactly how fresh it is:

• timestamp is when the price was collected.
• age_seconds is how old that price was when you received it.
• stale is true if the price is more than two hours old, which means a collection was missed.

Always show an "as of" time built from timestamp, not your server clock. If stale is true, hide the board or note that prices are delayed. Avoid wording that suggests second-by-second updates; an honest timestamp keeps customer trust.

Displaying Prices Responsibly

A karat price per gram is an indicative metal value, not an appraisal, a retail price, or an offer to buy. Retail prices add labor, design, stones, and margin; buy prices reflect refining costs. Say so plainly next to the numbers.

Two references are worth knowing:

• FTC Guides for the Jewelry, Precious Metals, and Pewter Industries (16 CFR Part 23). The Guides treat inaccurate karat representations as deceptive and say products below 10 karat should not be described as gold in the United States. If you display a karat value next to a product, make sure the karat claim on that product is accurate. Our guide on how to tell if gold is real covers verification methods.
• ISO 9202. This international standard defines the fineness values used in hallmarking, such as 375, 585, 750, and 916 for gold. If your stock is hallmarked in fineness, use the matching fineness grade rather than converting through karats.

Server-Side vs Browser Calls: Keeping Your Key Safe

The API accepts browser calls, but a key placed in front-end JavaScript is visible to any visitor, who could copy it and spend your monthly calls. Calling from your server avoids that and saves calls.

If you must call from a browser, use a dedicated key you can roll from your dashboard. On Shopify, theme code runs in the shopper's browser, so keep the key in an app proxy or a scheduled function that writes prices somewhere your theme can read, such as a metafield.

Caching on Your Side to Save Calls

Because the source collects new prices hourly, calling the API on every page view wastes calls on the same price. Store the response and refresh it on a schedule. The table below shows how refresh frequency maps to monthly usage for one endpoint in a 31-day month.

The last row is the expensive mistake. Caching turns traffic-dependent usage into a fixed number of calls. If you show gold karat prices and silver fineness grades, double the figures.

Only successful calls count toward your quota. Paid plans get a 10% grace allowance, after which calls pause until the month resets on the 1st (UTC) or you upgrade. There are no overage bills. Compare plans on the pricing page.

Step by Step: Adding Live Karat Prices to Your Site

Step 1: Create a Free Account and a Key

Sign up for free. The Free plan includes 10 calls a month on every endpoint, no card required. Create a key in your dashboard. It starts with kt_live_ and is shown only once, so store it in an environment variable.

Step 2: Make Your First Call

curl -H "X-API-Key: kt_live_your_key_here" "https://api.karatology.com/v1/karat?unit=g"

Step 3: Read the Response

The values below are illustrative and match the $4,000.00 example above.

{
  "success": true,
  "timestamp": "2026-11-10T14:00:07.389Z",
  "age_seconds": 1260,
  "stale": false,
  "currency": "USD",
  "unit": "g",
  "metal": "gold",
  "spot_price_toz": 4000,
  "karats": [
    { "karat": "24K", "purity": 0.999, "fineness": 999, "price": 128.4743 },
    { "karat": "18K", "purity": 0.75, "fineness": 750, "price": 96.4522 },
    { "karat": "14K", "purity": 0.5833, "fineness": 583.3, "price": 75.0141 }
  ]
}

Step 4: Fetch on Your Server With a Cache

This Node.js function keeps the last good response in memory and refreshes it at most once an hour.

let cached = null;
let fetchedAt = 0;
const MAX_AGE_MS = 60 * 60 * 1000;

export async function getKaratPrices() {
  if (cached && Date.now() - fetchedAt < MAX_AGE_MS) return cached;
  const res = await fetch("https://api.karatology.com/v1/karat?unit=g", {
    headers: { "X-API-Key": process.env.KARATOLOGY_API_KEY },
  });
  if (!res.ok) {
    if (cached) return cached; // keep showing the last good prices
    throw new Error("Price request failed: " + res.status);
  }
  cached = await res.json();
  fetchedAt = Date.now();
  return cached;
}

On serverless platforms, memory may not survive between requests, so use your platform's data cache or a scheduled job instead.

Step 5: WordPress and WooCommerce

WordPress transients give you the same pattern in PHP.

function karatology_karat_prices() {
  $cached = get_transient('karatology_karat_g');
  if ($cached !== false) return $cached;
  $res = wp_remote_get('https://api.karatology.com/v1/karat?unit=g', array(
    'headers' => array('X-API-Key' => KARATOLOGY_API_KEY),
    'timeout' => 10,
  ));
  if (is_wp_error($res) || wp_remote_retrieve_response_code($res) !== 200) return null;
  $data = json_decode(wp_remote_retrieve_body($res), true);
  set_transient('karatology_karat_g', $data, HOUR_IN_SECONDS);
  return $data;
}

Define KARATOLOGY_API_KEY in wp-config.php, not in a theme file.

Step 6: Render Prices With a Timestamp

Round each price to two decimals for display, print the "as of" time from timestamp, and show a delayed notice when stale is true. Place your disclaimer directly under the board, not in the footer.

Step 7: Handle Errors Gracefully

• 401 invalid_api_key: the key is wrong or was revoked.
• 429 rate_limited or quota_exceeded: wait the seconds given in Retry-After, and watch X-Quota-Remaining to see trouble coming.
• 503 prices_unavailable: retry shortly and keep showing your cached prices.

Errors never count toward your quota. The full list of fields and error codes is in the API documentation.

Frequently Asked Questions

Start Free

You can have a live karat price board running in an afternoon. Create a free account for 10 calls a month on every endpoint, read the API documentation, and compare plans on the pricing page when you are ready to go live. For a quick number on a single piece, our free gold karat calculator is always available.