DEV Community

Cover image for Sephora API Example: A Price and Stock Check Tool for an AI Agent
Happy Endpoint
Happy Endpoint

Posted on Originally published at Medium

Sephora API Example: A Price and Stock Check Tool for an AI Agent

Ask an AI agent what Rare Beauty's Soft Pinch Liquid Blush costs at Sephora, and the first thing it sees is the search result: "listPrice": "$16.00 - $25.00". Which number goes in the answer? The $16 is a 3.2 mL mini. The $25 is the 7.5 mL full size. Per millilitre, the mini costs 50% more.

That is not a rare case. I asked the Sephora API 15 shopping questions, typed the way a shopper types them, and 11 of the 15 products came back with a range instead of a price. Search itself did well: the first result matched the product named in 15 of 15 questions. The trouble starts after that, when the agent has to pick a size, a shade and a store.

What I asked, and how

The questions were the plain kind: "dior lip glow oil", "tatcha water cream", "ysl libre perfume", "dyson airwrap", "olaplex no 3", and ten more across makeup, skincare, hair and fragrance. For each one I ran what an agent connected to the Sephora API would run, on 4 November 2026:

  1. /search-by-keyword with the question, 10 results.
  2. /product-details for the product the shopper meant, which lists every size and shade as a SKU.
  3. /product-availability for that product's default SKU, within 10 miles of one of five US cities (New York, Chicago, Los Angeles, Houston, Seattle).

Over MCP, these are three tools: RapidAPI's gateway turns every endpoint of the API into one (how to connect it). So the raw responses below are exactly what a model would read. In all that was 116 search rows, 15 product records with 140 SKUs, and 204 store rows.

The search price is usually a range

Product Search says Default SKU Best value Smallest size pays
Rare Beauty Soft Pinch Blush $16.00 - $25.00 7.5 mL, $25 7.5 mL, $3.33/mL +50%
Drunk Elephant Protini $24.00 - $99.00 50 mL, $72 100 mL, $0.99/mL +62%
Glow Recipe Dew Drops $20.00 - $49.00 40 mL, $36 80 mL, $0.61/mL +118%
The Ordinary Niacinamide $6.00 - $10.80 30 mL, $6 60 mL, $0.18/mL +11%
Sol de Janeiro Bum Bum Cream $24.00 - $48.00 240 mL, $48 240 mL at $44, $0.18/mL +75%
Olaplex No.3PLUS $34.00 - $68.00 100 mL, $34 250 mL, $0.27/mL +25%
Tatcha The Water Cream $25.00 - $93.00 50 mL, $74 75 mL, $1.24/mL +34%
YSL Libre Eau de Parfum $38.00 - $225.00 90 mL, $185 100 mL, $1.40/mL +171%
Huda Beauty Easy Bake $24.00 - $42.00 2 x 6.5 g, $42 20 g, $2.00/g +100%

In 9 of the 11 ranges, the low end is the price of the smallest size. An agent that reports "from $24" for Drunk Elephant's Protini is quoting a 15 mL jar of a cream most people buy at 50 mL. An agent that reports the high end is often quoting the biggest bottle. Neither is what the shopper meant by "how much is it".

The product record does not settle it either. Each product has a default SKU (the currentSku in /product-details, the same SKU the search row points to for 13 of the 15), and it is often neither the cheapest nor the most common size. For YSL Libre it is the 90 mL bottle at $185. For Glow Recipe it is the 40 mL at $36, a size the search range never mentions.

The smallest size costs up to 171% more per mL

Per millilitre or gram, the smallest size cost more in all 9 products with a real choice of sizes, a median of 62% more than the best-value size. YSL Libre is the extreme: the 10 mL spray works out at $3.80/mL, the best value is $1.40/mL. And that best value is not the biggest bottle. The 100 mL at $140 costs less than the 90 mL at $185, and it is the one SKU with isOnlineOnly: true. An agent comparing sizes by eye would miss it. An agent that computes price per mL finds it at once.

Shades and models have prices too

One product, up to six prices

11 of the 15 products carried more than one list price across their SKUs. Sizes explain most of it, but not all. Laneige's Lip Sleeping Mask costs $24 in most flavours and $25 in three, two of them limited editions. Charlotte Tilbury's Matte Revolution costs $37, except in two shades at $39. So "how much is the Pillow Talk lipstick" has a right answer only after the agent resolves the shade to a SKU.

Dyson is the other kind of ambiguity. The search for "dyson airwrap" returned 7 different multi-stylers in the top 10, at $649, $699 and $749, plus attachments. The first one, the agent's natural pick, had isOutOfStock: true on its only SKU, and none of the 6 stores near Houston had it. A good answer there is a question back to the user: which Airwrap?

Store stock: read the units, not the label

Across the 204 store rows, 160 said "In Stock", 18 "Limited Stock" and 26 "Out of Stock". 14 of the 15 products were on a shelf somewhere near their city. Three details matter for an agent:

The label is not a unit count. 4 store rows said "In Stock" with exactly 1 unit on hand. 4 said "Limited Stock" with 5 or more, up to 21 for The Ordinary's serum in Houston. If the user is about to drive somewhere, inStoreAvailability is the number to pass on.

Some stores are inside Kohl's. 24 of the 204 rows were Sephora counters inside Kohl's stores (storeType is not SEPHORA), and 15 of them had the item. That is worth saying in the answer, because a shopper heading to "the Sephora in Jersey City" will not find a standalone store.

The search row's pickup flag says nothing about stores. pickupEligible was false on all 116 search rows, including the 14 products that were in stock nearby. It describes the search context, not shelves. Only /product-availability answers "can I pick it up today?"

The tool

None of this needs a model to reason about it. It needs a tool that does the arithmetic and hands the model a short answer: every size once with its price per mL or gram, the SKU for the shade the user named, and the nearest stores with units. Here is that tool, runnable as printed with a RapidAPI key:

"""A price and stock check tool for an AI agent, over the Sephora API on RapidAPI.

Three calls (search, product record, store stock) in, one small answer out: every size with
its price per mL or gram, the shade or size the shopper asked for, and the nearest stores
that have it.

    RAPIDAPI_KEY=... python3 sephora_price_check.py "rare beauty soft pinch liquid blush" Happy 40.758 -73.9855
"""
import json
import os
import re
import sys

import requests

HOST = "real-time-sephora-api.p.rapidapi.com"
BASE = os.environ.get("API_BASE", "https://" + HOST)


def headers():
    if "API_BASE" in os.environ:
        return json.loads(os.environ.get("API_HEADERS", "{}"))
    return {"x-rapidapi-host": HOST, "x-rapidapi-key": os.environ["RAPIDAPI_KEY"]}


def get(path, **params):
    r = requests.get(BASE + path, params=params, headers=headers(), timeout=60)
    r.raise_for_status()
    return r.json()


def dollars(text):
    m = re.search(r"\$([\d,]+(?:\.\d+)?)", text or "")
    return float(m.group(1).replace(",", "")) if m else None


def amount(size):
    """'0.25 oz/ 7.5 mL' -> (7.5, 'mL'), '0.21 oz/6 g' -> (6.0, 'g'). None if neither is given."""
    m = re.search(r"([\d.]+)\s*ml", size or "", re.I) or re.search(r"([\d.]+)\s*g\b", size or "", re.I)
    if not m:
        return None
    return float(m.group(1)), "mL" if "ml" in m.group(0).lower() else "g"


def sku_row(k):
    price = dollars(k.get("salePrice")) or dollars(k.get("listPrice"))
    a = amount(k.get("size"))
    return {
        "sku": k["skuId"],
        "option": k.get("variationValue"),
        "size": (k.get("size") or "").strip() or None,
        "price_usd": price,
        "was_usd": dollars(k.get("listPrice")) if k.get("salePrice") else None,
        "per_unit": "%.2f/%s" % (price / a[0], a[1]) if a and price else None,
        "online_only": k.get("isOnlineOnly"),
        "sold_out_online": k.get("isOutOfStock"),
    }


def check_price(query, option=None, lat=None, lon=None):
    rows = get("/search-by-keyword", keyword=query, pageSize=10)
    full_size = [r for r in rows if not r["displayName"].lower().startswith("mini ")]
    if not full_size:
        return {"error": "no product found for %r" % query}
    product = full_size[0]
    details = get("/product-details", productId=product["productId"])

    skus, seen = [], set()
    for k in [details["currentSku"]] + details.get("regularChildSkus", []):
        if k["skuId"] not in seen:
            seen.add(k["skuId"])
            skus.append(sku_row(k))
    chosen = skus[0]  # the product's default SKU
    if option:
        chosen = next((s for s in skus if option.lower() in (s["option"] or "").lower()), chosen)

    # Many shades share a size and a price, spelled several ways: list each size and price once
    sizes = {}
    for s in skus:
        key = (amount(s["size"]) or s["size"], s["price_usd"])
        sizes.setdefault(key, dict(s, options=0))["options"] += 1
    answer = {
        "product": "%s %s" % (product["brandName"], product["displayName"]),
        "url": details.get("fullSiteProductUrl"),
        "chosen": chosen,
        "sizes": [{"size": v["size"], "price_usd": v["price_usd"], "per_unit": v["per_unit"],
                   "online_only": v["online_only"], "options": v["options"]} for v in sizes.values()],
    }
    if lat is not None:
        stock = get("/product-availability", skuId=chosen["sku"], latitude=lat, longitude=lon, radius=10)
        stores = stock["data"]["stores"]
        answer["stores"] = [{"store": x["displayName"], "miles": x["distance"], "units": x["inStoreAvailability"],
                             "status": x["availabilityStatus"], "inside_kohls": x["storeType"] != "SEPHORA"}
                            for x in stores if x["inStoreAvailability"] > 0][:5]
        answer["stores_checked"] = len(stores)
    return answer


if __name__ == "__main__":
    q = sys.argv[1]
    opt = sys.argv[2] if len(sys.argv) > 2 else None
    lat, lon = (float(sys.argv[3]), float(sys.argv[4])) if len(sys.argv) > 4 else (None, None)
    result = check_price(q, opt, lat, lon)
    print(json.dumps(result, indent=1))
    print("answer: %d characters" % len(json.dumps(result, separators=(",", ":"))))
Enter fullscreen mode Exit fullscreen mode

For the blush in the shade Happy, near Times Square, it chose SKU 2362085 (7.5 mL, $25, $3.33/mL), listed the two sizes once each (14 shades of the full size, 8 of the mini at $5.00/mL), and returned the five nearest stores with units, Times Square first with 97. The whole answer was 1,007 characters. The three raw responses behind it run to about 199,000 characters in my test calls (13,228 for the search, 129,780 for the product record, about 55,700 for the stores), roughly 49,700 tokens at four characters a token. That is an estimate, since every model's tokenizer differs, but the gap is the point.

To give it to Claude or another agent, wrap check_price as one tool with three inputs (query, option, and a location), in whatever framework you use, or as a tool of your own MCP server next to the gateway's endpoint tools.

Pitfalls in the data

Size strings are free text. Fenty's Gloss Bomb has 10 SKUs and 7 spellings of its size, among them 0.3 oz/ 9 mL, 0.30 oz, 0.3 oz/9 oz and 0.30 oz/9 g. Huda Beauty's powder has 7. Parse the mL or gram figure, and treat a size with neither as unknown. Four SKUs had no size at all.

Same size, different price. Sol de Janeiro's Bum Bum Cream has two 240 mL SKUs, at $48 and $44, and nothing in the size field says how they differ. Tatcha and Drunk Elephant list refills of the 50 mL at $68 and $63 next to the jars at $74 and $72; there the size says "Refill". Show the user both.

Minis live in two places. A mini is often both a SKU of the main product and a separate "Mini ..." product in search. 39 of the 116 search rows were minis or sets. The tool skips the "Mini" products in search and gets the mini sizes from the main record, so each size appears once.

Sales are rare and live in salePrice. Only 1 of the 116 search rows was on sale (a Charlotte Tilbury mini lipstick set, $26 down to $18.20). When salePrice is set, it is the price, and listPrice is the was-price.

The range and the record can disagree. For 14 of the 15 products, the search range matched the lowest and highest SKU prices exactly. For Laneige's mask, the range started at $23 while every SKU in the product record cost $24 or $25. Quote the record.

What I would do next

Add a size preference to the tool ("the usual size", "the best value", "travel size") so the agent can answer the question the user asked without asking back, and cache product records for a day, since prices change less often than stock.

The Sephora API is on RapidAPI with a free plan for testing. More examples are in the Sephora API repo on GitHub, and the Sephora API overview on LinkedIn covers what the data includes. Building a shopping agent on beauty data, or need the catalog as a dataset? Get in touch.

Top comments (0)