Gift Guide API: Build a Holiday Gift Guide by Budget and Stock

A gift guide has one job on a busy November afternoon: send a reader to something they can buy. That is harder than it sounds, because a pick can be out of stock, or priced above the budget the page promised, by the time the reader clicks. A Gift Guide API keeps both promises by filtering gifts by price and reading how many stores have each one in stock, instead of trusting a list written weeks ago. The Affiliate.com Products API finds gifts in a budget, and the Price History API reports the price and stock for each one. The demo below uses prices last pulled November 12, 2026. Pick a budget and an interest, then switch the stock filter on and off.

What a gift guide has to get right

A guide makes three promises. The first is a budget: gifts under $50 should be under $50 today, not last month. The second is a fit: a reader who picked an interest should see things that belong in it. The third is availability: every pick should be something a reader can add to a cart. The first two are filters. The third is a judgment, and it is the one most guides get wrong.

Stock is not a yes or no. A product in stock at one store may sell out by the afternoon, while the same product in stock at nine stores is safe to feature. The demo therefore counts the stores that have each gift in stock today and marks a gift as thin when fewer than five do. A page can then decide what to do with thin gifts: hide them, move them to the end or add a note.

The comparison is fair to the reader because it uses the lowest in-stock price. A cheaper listing that is out of stock is left out, because nobody can buy it. The price on the card is the price a reader would actually pay.

Who builds with a gift guide API

Publishers build the obvious version: a seasonal page with picks by budget, refreshed as prices move. A guide that rebuilds itself every night does not need an editor to recheck forty links the week before the holidays. Newsletter teams use the same data to choose the five picks that go in a send, and to confirm the day before that all five are still in stock.

Retail and gifting apps build the interactive version. A budget slider, an interest picker and a list that updates as the reader changes them is the demo above with a design of your own. Our post on planning holiday content with product data lists what to check before gift-guide season starts.

AI shopping assistants answer the same question in a sentence. A reader who asks for a good gift under $100 for someone who likes cooking needs real products with real prices, and the assistant should avoid recommending something that is out of stock. The checks in this article are small enough to run inside a tool call.

Try the gift guide

This guide runs on real results from the Price History API for popular gifts. The page holds a rotating set that is rebuilt every night, and it shows up to six gifts for the budget and interest you pick, in a different order on each visit. Change the budget, change the interest and turn the stock filter off to see what it was hiding. The request below it is the exact call that returns each gift, and the second tab shows the short functions behind the guide.

Finding gifts, then reading their stock

The work happens in two requests. The first uses the Products API to find in-stock products in a price range, with a barcode so each result can be looked up again. The request below finds portable speakers between $50 and $100. Replace the name with any gift idea, and the two numbers with the reader’s budget.

POST https://api.affiliate.com/v1/products

{
  "search": [
    { "field": "name", "operator": "LIKE", "value": "bluetooth speaker||portable speaker" },
    { "field": "final_price", "operator": "BETWEEN", "value": "50|100" },
    { "field": "availability", "operator": "=", "value": "InStock" },
    { "field": "currency", "operator": "=", "value": "USD" },
    { "field": "image_url", "operator": "NOT NULL" },
    { "field": "barcode", "operator": "NOT NULL" }
  ],
  "fields": ["name", "brand", "barcode", "final_price", "availability", "image_url", "merchant.name"],
  "per_page": 25
}

Treat the result as a list of candidates. A keyword search returns accessories and listings from stores of every size, so a guide should curate the gifts it features and keep their barcodes. The second request then takes one barcode and returns every store that sells it, with the current price and availability for each, which is what the demo reads.

Send include_series as false, as the demo does, when a guide needs only today’s price and stock. The response is much smaller, because it leaves out the daily history.

Turning the responses into a guide

The guide is two small functions. The first reads one response and returns the price, the number of stores that have the gift in stock and the number of stores that report it today. The second filters a list of those results by budget and by stock depth.

// listings: the data array of one price-history response (include_series false)
function summarizeGift(listings) {
  const latest = listings.map(l => l.stats.last_date).sort().pop();
  const live = listings.filter(l => l.stats.last_date === latest);
  const inStock = live.filter(l => l.product.availability === "InStock");
  return {
    price: Math.min(...inStock.map(l => l.stats.current.final_price)),
    storesInStock: inStock.length,
    stores: live.length
  };
}

// gifts: one summarizeGift() result per gift, plus its name and barcode
function buildGuide(gifts, { min, max, minStores = 5 }) {
  return gifts
    .filter(g => g.price >= min && g.price < max)
    .filter(g => g.storesInStock >= minStores) // skip thin stock
    .sort((a, b) => a.price - b.price);
}

The threshold is a choice, and a guide should make it on purpose. Five stores is a sensible floor for a mainstream gift, because it means a store or two selling out does not empty the pick. A page that features niche gifts may accept fewer. What matters is that the rule is written down and applied the same way to every gift.

What the November 10, 2026 pull shows

We ran the same request on November 10, 2026 for the twenty-four gifts in that day’s set, across four interests. Four of the twenty-four were in stock at fewer than five stores, which the stock filter in the demo would hide. The table splits the set by budget.

This table is fixed to November 10, 2026. The demo above is rebuilt every night with a different set of gifts, so both its products and its numbers will change as the holidays approach. Treat the table as a record of one day and the demo as the live version of the same check.

A handful of gifts is a small sample and not a market study. Each figure describes one product across the stores that report it, in US dollars, and a gift is counted as in stock at a store only when that store reported it on the latest date.

What to check before gift-guide season

A guide earns trust when it behaves the same way on the last day as on the first, so a few habits are worth building in before traffic arrives.

Check stock again at click time. The guide reads stock when it is built, and stock changes during the day. A page should confirm availability before it sends a reader to a store. Handling out-of-stock and price-changed offers lays out how an agent can do that.

Show the budget you filtered on. “Under $100” is a promise, so recheck the price when the page is built, not when the pick was written. Prices move daily in November, and a gift that was $95 last week may be $110 now.

Match on the barcode. Two colors or two bundles of the same model are different products with different barcodes, and mixing them makes a price or a stock count look wrong. Barcode search explains why the barcode comes first.

Keep the list curated. A keyword search returns accessories, cases and look-alikes along with the real gifts. Pick the gifts yourself, store their barcodes and let the API keep the prices and stock current.

Getting started in three steps

Moving from the demo to a guide of your own takes three steps, and the request panel above already contains the second one.

Keeping a gift guide current

Prices and stock move daily during the holidays, so a guide that updates weekly will be wrong most of the time. The demo above is rebuilt every night and shows the date it was last pulled, so readers can see how old the figures are. A page of your own can do the same: pull on a schedule, store the result and print the time beside it. How often product pages should be updated discusses how often is often enough.

A guide can also say something about price. Comparing regular price with final price shows how to test a discount claim, and a gift guide that adds the check turns a list of picks into a list of picks that hold up.

{
  "target_type": "barcode",
  "target_ids": [
    "195949688522"
  ],
  "currency": "USD",
  "include_series": false,
  "include_stats": true,
  "include_product": true,
  "per_page": 25
}