Ulta Beauty API - Search, Prices, Shades, Store Stock
Ulta Beauty product data as structured JSON - search ulta.com or list any category with list and sale price, discount, promo text, rating and review count, read one product with every shade or size, GTIN, ingredients, ship, pickup and same-day options and the five most recent reviews, and check in-store pickup stock of one shade at the 10 stores nearest a ZIP. 4 endpoints, 1 credit each.
Ulta Beauty via Scavio
Search Ulta Beauty and list any category: list and sale price, discount, promo text, rating, review count, badge and shade count, 64 products per page. Read one product for the shade or size you pick, with every variant, GTIN, ingredients, ship, pickup and same-day options and the five most recent reviews. Check whether one shade is in stock for pickup at the 10 Ulta stores nearest a ZIP. All endpoints return structured JSON.
When to trigger
Use this skill when the user asks to:
- Find makeup, skincare, hair care or fragrance at Ulta Beauty by keyword
- List the products in an Ulta category (lipstick, mascara, shampoo) with prices and ratings
- Check an Ulta product's price, sale price and discount, or what is on sale
- List the shades or sizes of a product and which are available
- Find which Ulta stores near a ZIP have a shade in stock for pickup
- Read the latest Ulta reviews, ingredients or usage for a product
- Look up a product's GTIN (UPC)
- Compare Ulta prices with Sephora or other retailers, or monitor them
Setup
Get a free API key at scavio.dev (50 free credits to get started, no card required):
export SCAVIO_API_KEY=sk_live_your_key
If you do not have a key yet
An agent running this skill without SCAVIO_API_KEY set will get 401 on every
call below. The whole path from nothing to a working key is self-serve:
- Sign up at dashboard.scavio.dev - email or Google, no card required.
- A key is created for the account automatically at signup. It is on the dashboard under API Keys, ready to copy.
- A new account starts with 50 credits. Every endpoint in this skill costs 1 credit.
When the balance runs out the API answers 402 with a JSON body carrying
billing_url. Topping up needs no code change - the same key keeps working.
Every request is a POST with a JSON body and:
Authorization: Bearer $SCAVIO_API_KEY
Endpoints
Base URL: https://api.scavio.dev. All Ulta Beauty endpoints cost 1 credit.
| Endpoint | Credits | What it returns |
|---|---|---|
POST /api/v1/ulta/search | 1 | 64 products per page plus sponsored placements: product id, sku id, brand, name, URL, image, list and sale price (and the range when shades are priced differently), discount, promo text, rating, review count, badge, shade count, limited-stock and sponsored flags |
POST /api/v1/ulta/category | 1 | One category's products in the same shape, with the category title and total results |
POST /api/v1/ulta/product | 1 | One product for the selected shade or size: list and sale price, discount, availability, GTIN, rating, review count, badges, summary, description, usage, ingredients, restrictions, category and breadcrumbs, images, every shade or size variant, ship / pickup / same-day options, and the five most recent reviews |
POST /api/v1/ulta/stores | 1 | In-store pickup stock of one shade at the 10 Ulta stores nearest a ZIP: store id, name, address, distance, open-now label, curbside label, in_stock and the availability label |
Workflow
- Find products: call
/ulta/searchwithquery, or/ulta/categorywith a category path like/shop/makeup/lips/lipstick. Each row has aurl, aproduct_idand asku_id. - One product in full: call
/ulta/productwith the row'surl. Addskuto pick a shade or size;variants[]lists every one with itssku_id. - Who has it nearby: call
/ulta/storeswith theproduct_id, the shade'ssku_idand the user'szip. Stock is per shade, so pass the exactsku_idthe user wants.
Parameters
Search (/search)
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string | required | Keywords (1-200 chars) |
page | integer | 1 | 1-based page (1-100), 64 products per page plus sponsored placements |
Category (/category)
| Parameter | Type | Default | Description |
|---|---|---|---|
category | string | required | An ulta.com category that lists products: the full URL, or its path (/shop/makeup/lips/lipstick or makeup/lips/lipstick) |
page | integer | 1 | 1-based page (1-100), 64 products per page plus sponsored placements |
Product (/product)
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string | required | Ulta product page URL, /p/<name>-<productId> (the url of a search or category row). The name part is required |
sku | string | URL's ?sku=, else the default | Shade or size to select, by sku id (a variants[].sku_id) |
Stores (/stores)
| Parameter | Type | Default | Description |
|---|---|---|---|
product_id | string | required | Ulta product id, e.g. pimprod2057119 |
sku_id | string | required | Sku id of the shade or size, a sku_id or variants[].sku_id |
zip | string | required | US ZIP code to search around |
Examples
curl -X POST https://api.scavio.dev/api/v1/ulta/stores \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"product_id": "pimprod2057119", "sku_id": "2648428", "zip": "10001"}'
Captured response (Maybelline Serum Lipstick near Manhattan 10001; trimmed to 3 of 10 stores):
{
"data": {
"product_id": "pimprod2057119",
"sku_id": "2648428",
"zip": "10001",
"count": 10,
"in_stock_count": 7,
"stores": [
{
"store_id": "1638",
"name": "2 Herald Square",
"address": "51 West 34th Street, Suite 110, New York, NY 10001",
"city": "New York",
"state": "NY",
"zip": "10001",
"distance_miles": 0.17,
"is_open": true,
"open_label": "Open until 8:00 pm",
"curbside_label": null,
"in_stock": false,
"availability": "Out of Stock"
},
{
"store_id": "1899",
"name": "Ulta Beauty",
"address": "620 Avenue of the Americas, Ste 0105, New York, NY 10011",
"city": "New York",
"state": "NY",
"zip": "10011",
"distance_miles": 0.63,
"is_open": true,
"open_label": "Open until 7:00 pm",
"curbside_label": null,
"in_stock": true,
"availability": "In Stock"
},
{
"store_id": "1402",
"name": "Upper East Side",
"address": "188 East 86th Street, New York, NY 10028",
"city": "New York",
"state": "NY",
"zip": "10028",
"distance_miles": 2.81,
"is_open": true,
"open_label": "Open until 7:00 pm",
"curbside_label": null,
"in_stock": true,
"availability": "In Stock"
}
]
},
"response_time": 3096,
"credits_used": 1
}
A captured /product answer for the same product (summary, description, ingredients, images, breadcrumbs trimmed; 2 of 16 variants, 1 of 5 reviews):
{
"product_id": "pimprod2057119",
"sku_id": "2648428",
"name": "Serum Lipstick",
"brand": "Maybelline",
"url": "https://www.ulta.com/p/serum-lipstick-pimprod2057119?sku=2648428",
"variant_label": "Crop Top (light nude pink)",
"variant_type": "Color",
"size": "0.12 oz",
"list_price": 9.99,
"list_price_range": null,
"sale_price": 4.99,
"sale_price_range": null,
"discount": 5,
"currency": "USD",
"availability": "InStock",
"gtin": "041554100051",
"rating": 4.7,
"review_count": 431,
"questions_count": 1,
"badges": ["Sale"],
"category": "Makeup:Lips:Lipstick",
"variants": [
{ "sku_id": "2648432", "name": "Avenue A", "shade_description": "deep chocolate brown", "selected": false, "available": true, "out_of_stock_label": null },
{ "sku_id": "2648514", "name": "Blind Date", "shade_description": "midtone bricky mauve", "selected": false, "available": true, "out_of_stock_label": null }
],
"fulfillment": {
"ship": { "eligibility": "in_stock", "state": "active", "label": "Free standard shipping over $35", "message": "In stock and ready to ship", "stock_status": null, "speed": "Usually ships in 24 hours" },
"pickup": { "eligibility": "change_store", "state": "unavailable", "label": "Unavailable", "message": null, "stock_status": null, "speed": null },
"same_day": { "eligibility": "change_address", "state": "active", "label": "Delivered for $6.95", "message": "Check your address to view availability", "stock_status": null, "speed": "Get by 8PM today if ordered before 4PM" }
},
"recent_reviews": [
{ "title": "i wouldn't say matte, but its ok", "body": "glides on and king lasting... a little greasy looking. which i personally do not care for. I layer with lip liners to achieve the look I want. It does stay on! so that's good", "rating": 3, "date": "2026-10-27", "author": "Vanessa", "location": "ai" }
]
}
import requests
BASE = "https://api.scavio.dev"
# Your key from https://scavio.dev. Load it from your environment or secret
# store in real code - keep it out of source control.
API_KEY = "sk_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def ulta(endpoint, body):
r = requests.post(f"{BASE}/api/v1/ulta/{endpoint}", headers=HEADERS, json=body, timeout=120)
r.raise_for_status()
return r.json()["data"]
# 1. Search, organic results only, one row per product
rows = [p for p in ulta("search", {"query": "lipstick"})["products"] if not p["sponsored"]]
top = rows[0]
print(top["brand"], top["name"], top["list_price"], "sale", top["sale_price"])
# 2. The product and its shades
item = ulta("product", {"url": top["url"]})
shade = next(v for v in item["variants"] if v["available"])
# 3. Which nearby stores have that shade for pickup
near = ulta("stores", {"product_id": item["product_id"], "sku_id": shade["sku_id"], "zip": "10001"})
for s in near["stores"]:
if s["in_stock"]:
print(shade["name"], "at", s["name"], s["address"], s["distance_miles"], "mi")
Response shapes
Every response uses the envelope { data, response_time, fetched_at, credits_used, credits_remaining }. Nothing is cached; fetched_at is when Ulta Beauty answered.
- search / category -
query(search) orcategory,title,url(category),page,page_size,total_results,total_pages,count,sponsored_count,has_more,products[](position,product_id,sku_id,brand,name,url,image,list_price,list_price_range,sale_price,sale_price_range,discount,promo_text,rating,review_count,badge,variant_label,is_limited_stock,sponsored). - product -
product_id,sku_id,name,brand,url,variant_label,variant_type,size,list_price,list_price_range,sale_price,sale_price_range,discount,currency,availability,gtin,rating,review_count,questions_count,badges[],summary,description,usage,ingredients,restrictions,category,category_path[],breadcrumbs[]{label,url},images[],variants[]{sku_id,name,shade_description,selected,available,out_of_stock_label,image,swatch},fulfillment{ship,pickup,same_day: {eligibility,state,label,message,stock_status,speed}},recent_reviews[]{title,body,rating,date,author,location}. - stores -
product_id,sku_id,zip,count,in_stock_count,stores[](store_id,name,address,city,state,zip,distance_miles,is_open,open_label,curbside_label,in_stock,availability).
Guardrails
- Prices are in dollars:
9.99is $9.99.discountis a dollar amount off, not a percentage:5is $5 off. - When shades are priced differently,
list_price/sale_priceare the low end andlist_price_range/sale_price_rangehold the range as shown ("$4.99 - $9.99"). Quote the range, or call/productwith the shade'sskufor one exact price. sale_priceisnullwhen the item is not on sale; the price paid is thenlist_price.- Listing pages carry sponsored placements on top of the 64 organic cards (
countcan be 73), and they can repeat products from other pages. Filter onsponsoredand dedupe byproduct_idwhen merging pages. /storesreports In Stock or Out of Stock per store for pickup; Ulta does not publish unit counts. Never quote a quantity.- Store stock is per shade: a store can have one shade and not another, so always check the exact
sku_id. recent_reviewsare the five most recent reviews the product page shows; there is no endpoint that pages older reviews.- Never fabricate prices, shades or stock. Only return what the API returned, with the product
url.
Failure handling
400means a missing or invalid parameter (noquery, aurlorcategorythat is not on ulta.com, a non-numericskuorsku_id, aproduct_idnot likepimprod2057119, or an unknown ZIP).401means the API key is invalid or missing. CheckSCAVIO_API_KEY.402means the balance is out of credits. The body carriesbilling_url.404on/productmeans no such product, or a URL without its name part (/p/<productId>alone).404on/categorymeans a path with no product grid, such as the/shop/makeuplanding page; use a deeper path.404on/storesmeans no Ulta store near that ZIP. Not charged.429means rate or usage limit exceeded. Wait before retrying. See rate limits.502means Ulta Beauty is temporarily unavailable. It is not charged; retry after a few seconds.
SDKs
pip install scavio==0.32.0
npm install scavio@0.32.0
import { Scavio } from "scavio";
const scavio = new Scavio(); // reads SCAVIO_API_KEY
const { data: found } = await scavio.ulta.search({ query: "lipstick" });
const lips = await scavio.ulta.category({ category: "/shop/makeup/lips/lipstick" });
const { data: item } = await scavio.ulta.product({ url: found.products[0].url });
const near = await scavio.ulta.stores({ product_id: item.product_id, sku_id: item.sku_id, zip: "10001" });
MCP: the Scavio MCP server exposes all 4 endpoints as tools (search_ulta, get_ulta_category, get_ulta_product, get_ulta_stores). Ulta Beauty is opt-in: add ulta to SCAVIO_PLATFORMS.
{
"mcpServers": {
"scavio": {
"command": "npx",
"args": ["-y", "@scavio/mcp-server@0.30.0"],
"env": {
"SCAVIO_API_KEY": "sk_live_your_key",
"SCAVIO_PLATFORMS": "default,ulta"
}
}
}
}
Docs
Full reference per endpoint: search, category, product, stores. Overview: Ulta Beauty API.
Related skills
- Downloads
- 122All time
- Security audit
- Pass
- Last updated
- 2w ago
- Current version
- v1.0.0
- License
- MIT-0
