Sephora APIsephora.com ↗
Access Sephora's product catalog, SKU variants, customer reviews, brand listings, and category data via 6 structured API endpoints.
What is the Sephora API?
The Sephora API covers 6 endpoints that surface product catalog data, customer reviews, brand listings, and search suggestions from Sephora.com. Use get_product_details to retrieve SKU variants, list prices, and availability flags for any product, or search_products to query the catalog by keyword with sorting and pagination. Each endpoint returns structured JSON ready to integrate into beauty apps, price trackers, or retail analytics pipelines.
curl -X GET 'https://api.parse.bot/scraper/5e13ff7b-6caf-4ee9-ba66-b042ee663109/search_products?page=1&sort=bestselling&limit=5&query=lipstick' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace sephora-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Sephora SDK — search, browse, and review beauty products."""
from parse_apis.sephora_api import (
Sephora, SearchSort, CategorySort, CategoryId, ProductNotFound
)
client = Sephora()
# Search for bestselling lipstick products, capped at 5 total items.
for summary in client.productsummaries.search(query="lipstick", sort=SearchSort.BESTSELLING, limit=5):
print(summary.brand_name, summary.display_name, summary.rating)
# Drill into the first result's full details via the summary/detail navigation.
summary = client.productsummaries.search(query="foundation", limit=1).first()
if summary:
detail = summary.details()
print(detail.hero_image_alt_text, detail.current_sku.list_price)
# Walk the product's reviews sub-resource.
for review in detail.reviews.list(limit=3):
print(review.user_nickname, review.rating, review.submission_time)
# Fetch a product directly by ID and handle not-found gracefully.
try:
product = client.products.get(product_id="P510799")
print(product.hero_image_alt_text, len(product.regular_child_skus), "variants")
except ProductNotFound as exc:
print(f"Product gone: {exc.product_id}")
# Browse a category using the CategoryId enum.
makeup = client.category(category_id=CategoryId.CAT140006)
for item in makeup.products(sort=CategorySort.BESTSELLING, limit=3):
print(item.brand_name, item.value, item.rating)
# List available brands.
for brand in client.brands.list(limit=3):
print(brand.name, brand.slug, brand.product_count)
print("exercised: productsummaries.search / details / products.get / reviews.list / category.products / brands.list")
Full-text search over Sephora's product catalog by keyword. Returns matching products with brand, pricing, rating, and image data, plus category facets and total result count. Paginates via page number. Each product carries a productId usable with get_product_details and get_product_reviews.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination |
| sort | string | Sort order for results |
| limit | integer | Number of results per page |
| queryrequired | string | Search keyword |
{
"type": "object",
"fields": {
"keyword": "string, the search keyword used",
"products": "array of product objects with brandName, displayName, productId, rating, reviews, currentSku, heroImage, targetUrl",
"categories": "array of category facets with displayName, nodeStr, recordCount",
"totalProducts": "integer, total number of matching products"
},
"sample": {
"data": {
"keyword": "lipstick",
"products": [
{
"rating": "4.5997",
"reviews": "712",
"brandName": "MAC Cosmetics",
"heroImage": "https://www.sephora.com/productimages/sku/s2837425-main-zoom.jpg?imwidth=270",
"productId": "P510799",
"targetUrl": "/product/mac-cosmetics-m-a-cximal-silky-matte-lipstick-P510799?skuId=2837425",
"currentSku": {
"skuId": "2837425",
"listPrice": "$16.00 - $25.00",
"isBestseller": true
},
"displayName": "M·A·Cximal Silky Matte 12HR Wear Lipstick"
}
],
"categories": [
{
"nodeStr": "cat140006",
"displayName": "Makeup",
"recordCount": "150"
}
],
"totalProducts": 151
},
"status": "success"
}
}About the Sephora API
Product Search and Discovery
The search_products endpoint accepts a required query string plus optional page, limit, and sort parameters (bestselling, price_asc, price_desc). Responses include a products array with per-item fields: brandName, displayName, productId, rating, reviews, currentSku, heroImage, and targetUrl. A categories array of facets and a totalProducts count are also returned, letting you build filtered browse experiences without separate category calls.
The get_search_autocomplete endpoint takes a query string and returns a sections object with three named arrays — Search Suggestions, Products, and Categories — along with per-section result counts in total_num_results_per_section. This is useful for building live search UIs or auditing which product names Sephora surfaces for a given term.
Product Details and SKU Variants
get_product_details takes a Sephora product_id (e.g., P510799) and returns the full product object. Key response fields include currentSku (with skuId, listPrice, skuImages, and actionFlags), regularChildSkus (all available variant SKUs with pricing and images), and ancillarySkus for related product recommendations. Availability state is expressed through actionFlags inside each SKU object.
Reviews, Brands, and Category Browsing
get_product_reviews returns paginated review data for a product. Each entry in the Results array includes Id, Rating, ReviewText, Title, UserNickname, SubmissionTime, Photos, and ContextDataValues. Control pagination with limit and offset params. get_brands requires no inputs and returns a full brand list with name, slug, and product_count aggregated across Skincare, Makeup, Fragrance, and Hair categories. get_category_products accepts a category_id (e.g., cat140006 for Makeup) with optional page, sort, and limit, and returns a response object containing a results array, facets, groups, sort_options, and total_num_results.
The Sephora API is a managed, monitored endpoint for sephora.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when sephora.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official sephora.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track price changes across SKU variants using
listPricefromget_product_details - Build a keyword search feature for a beauty app using
search_productswithbestsellingsort - Aggregate customer sentiment by pulling
RatingandReviewTextfromget_product_reviews - Generate a brand directory with product counts using
get_brands - Populate category browsing pages using
get_category_productswith facets and sort options - Power live search autocomplete with categorized suggestions from
get_search_autocomplete - Compare product availability flags across variants using
actionFlagsinregularChildSkus
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Sephora have an official public developer API?+
What does `get_product_details` return beyond basic product info?+
currentSku (with skuId, listPrice, skuImages, and actionFlags), regularChildSkus listing all purchasable variants with their own pricing and images, and ancillarySkus for associated product recommendations. heroImageAltText is also included for accessibility or SEO use cases.Does the reviews endpoint return Q&A or expert answers?+
get_product_reviews returns only customer-submitted reviews with fields like Rating, ReviewText, Title, UserNickname, SubmissionTime, Photos, and ContextDataValues. Q&A content is not currently covered. You can fork this API on Parse and revise it to add a Q&A endpoint.How does pagination work across endpoints?+
search_products and get_category_products use page and limit parameters. get_product_reviews uses offset and limit instead. get_brands and get_search_autocomplete do not support pagination — brands are returned in a single response aggregated across four major categories, and autocomplete results are returned in full per query.