Product by id or URL
5 credits/v1/sephora/productFull Sephora US product for a P-number or sephora.com/product URL. Title, brand, price, rating, images, ingredients. Advanced tier (5 credits).
product_id or url
Sephora APIGet Sephora product and store data with one API
Fetch Sephora US product detail, reviews, search, categories, brands, stores, and in-store availability as structured JSON with one SocialCrawl API key. Shared commerce schema. Reads are priced in credits.
/v1/sephora
11 active endpoints. 1 and 5 credit tiers.
- GET /v1/sephora/product
- GET /v1/sephora/reviews
- GET /v1/sephora/search
- GET /v1/sephora/search/suggestions
- GET /v1/sephora/category
- GET /v1/sephora/categories
- GET /v1/sephora/category/data
- GET /v1/sephora/brands
- GET /v1/sephora/brand/products
- GET /v1/sephora/stores
- GET /v1/sephora/availability
What Sephora endpoints does SocialCrawl ship?
Eleven live read endpoints for Sephora US. Product detail, reviews, keyword search, suggestions, category browse, taxonomy, brands, brand catalogues, store finder, and sku availability. Data API only.
Product reviews
5 credits/v1/sephora/reviewsWritten reviews for a Sephora product id. Rating, text, author, optional page. Advanced tier (5 credits).
product_id or url, page
Keyword search
5 credits/v1/sephora/searchSephora products matching a query. 60 per page, clean pagination. A miss returns empty and is not billed. Advanced tier (5 credits).
query, page, page_size
Search suggestions
1 credit/v1/sephora/search/suggestionsAutocomplete terms for a partial query. Standard tier (1 credit).
query
Category browse
5 credits/v1/sephora/categoryProducts in a Sephora category_id. Optional page. Advanced tier (5 credits).
category_id, page
Category taxonomy
1 credit/v1/sephora/categoriesRoot Sephora categories. Use ids here when browsing category products. Standard tier (1 credit).
(none)
Category children
1 credit/v1/sephora/category/dataOne category node and its children. Standard tier (1 credit).
id
Brand directory
1 credit/v1/sephora/brandsSephora brand short names. Feed a name into brand/products. Standard tier (1 credit).
(none)
Brand catalogue
5 credits/v1/sephora/brand/productsProducts from one brand short name. Optional page. Advanced tier (5 credits).
id, page
Store finder
1 credit/v1/sephora/storesSephora stores near a latitude,longitude pair. PlaceList shape. Standard tier (1 credit).
location_coordinate
Store availability
5 credits/v1/sephora/availabilityIn-store stock for one sku near a coordinate. Advanced tier (5 credits).
sku, location_coordinate
Sephora API11 endpoints supported
View docsProducts
Reviews
Search
Reference
Stores
Returns one Sephora product by id or URL: title, brand, description, price, rating, images, ingredients, and whether it is in stock.
Use it when you already have a product id (P427414) or a sephora.com/product URL. For discovery, start at search or category.
5 credits
GET/v1/sephora/product?product_id=P427414
$ curl https://www.socialcrawl.dev/v1/sephora/product?product_id=P427414 \
-H "x-api-key: sc_YOUR_API_KEY"idle
// Running this live needs your own API key. Hit "Try it" to see an example responseHow the Sephora API works
Sephora is a normal SocialCrawl data surface. You call GET /v1/sephora/… with an API key, spend credits on live misses, and get a single JSON envelope back.
Authenticate every call
Send your key in the x-api-key header. No Sephora OAuth app for public reads. The same key works across SocialCrawl platforms.
GET with query params
All Sephora routes are GET. Pass product_id, query, category_id, location_coordinate, sku as query strings. We validate formats before charging.
Pay in credits, not seats
Catalogue paths cost 5 credits. Taxonomy, brands, suggestions, and stores cost 1 credit. Cache hits cost 0.
Read one JSON envelope
Every response is the same shape: success, data, credits_used, credits_remaining, request_id, cached. Lists also carry pagination when the route pages.
The usual integration chain
Most products search or browse first, then deepen detail, reviews, and store stock only when needed.
01Search
GET /v1/sephora/search?query=…ProductList with P-ids
Resolve a product_id from a keyword.
02Product
GET /v1/sephora/product?product_id=…Full Product for the P-id
Deepen one item.
03Reviews
GET /v1/sephora/reviews?product_id=…ReviewList for the P-id
Customer language for that item.
04Availability
GET /v1/sephora/availability?sku=…Store stock for the sku
Shelf quantity near a coordinate.
request
GET /v1/sephora/search?query=moisturizer
Host: www.socialcrawl.dev
x-api-key: sc_your_api_key_here
GET /v1/sephora/product?product_id=P427414
GET /v1/sephora/reviews?product_id=P427414response envelope
{
"success": true,
"data": {
"product": {
"id": "P427414",
"title": "Natural Moisturizing Factors + Hyaluronic Acid Daily Moisturizer",
"brand": "The Ordinary",
"price": { "current": 12.5, "currency": "USD" },
"rating": { "average": 4.09, "count": 2841 }
}
},
"credits_used": 5,
"credits_remaining": 9995,
"request_id": "req_…",
"cached": false
}What lands in data
Field names match the rest of SocialCrawl where archetypes align. Parse once, reuse across platforms.
Productproduct, availability
id (P-number), title, brand, price, rating, images
ProductListsearch, category, brand/products
items[] with product id, title, price
ReviewListreviews
items[] with rating, text, author
Analytics / PlaceListcategories, brands, stores
taxonomy rows or store places near a coordinate
Inside the gateway
Same request lifecycle as every other /v1 platform endpoint. Sephora is not a sidecar.
- 01
Edge receives the call
Next.js catch-all routes into the Hono social API. We mint a request_id, authenticate the key, then enforce rate limit (600/min) and concurrency (50 in flight per key).
- 02
Validate, then debit
Registry lookup finds sephora/product (or reviews, search, stores). Required params and format checks run first. Invalid input returns 400 with no charge. Valid calls debit the tier cost atomically before upstream work.
- 03
Cache or fetch
A deterministic cache key is built from platform + resource + params. Hit: return immediately, credits_used = 0. Miss: Sephora catalogue paths run. Retries on 5xx/network with a circuit breaker if the source is unhealthy.
- 04
Normalize and return
Upstream JSON is mapped to commerce archetypes (Product, ProductList, ReviewList, PlaceList as applicable), validated against the canonical Zod schema, then wrapped in the success envelope and logged for billing audit.
Billing rules that matter in production
- product / reviews / search / category / brand/products / availability: 5 credits
- suggestions / categories / category/data / brands / stores: 1 credit
- Cache hit: 0 credits
- Empty search / hard fail: auto-refund
- Bad params: 400, never charged
- No credits: 402, never charged
- product_id is the product deepen key
- US catalogue only
- landings.platformBrief.platforms.sephora.api.billingRules.8
How we get the data
Sephora is public read data. We normalize it into the SocialCrawl schema so your code does not learn a second vendor SDK.
What Sephora is for this API
Public US product, reviews, search, category taxonomy, brands, store locations, and sku-level store stock. Read-only.
How SocialCrawl reaches it
Sephora catalogue paths behind the unified /v1 envelope.
What leaves our edge
Product, ProductList, ReviewList, PlaceList, and taxonomy analytics shapes.
What we do not ship live
No cart, Beauty Insider, or Europe catalogue routes.
field map sketch
product row→ product.*title, brand, price, rating
review pages→ ReviewListoptional page param
taxonomy / stores→ Analytics / PlaceListcategory ids; store locations
What this API is used for
The jobs this API is most often used for.
11active Sephora endpoints in the registry
1 / 5credit ladder for taxonomy/stores vs catalogue paths
Assortment, reviews, and store stock
Callers concentrate on search or taxonomy, then deepen detail, reviews, and availability for shortlisted items. P-id product and reviews at 5 credits, taxonomy and stores at 1, one SocialCrawl key.
Live misses are typically a few seconds. Some routes can take longer on cold cache.
Use case examples
Common ways teams put this data to work, and the stack each one tends to run.
Beauty merchandisers
Python, BIsearch or categories then category browse, product for P-id facts.
VoC teams
Node, warehousesreviews by product_id for customer language.
Local ops
scripts, mapsstores and availability by coordinate for shelf checks.
Call it in two lines
Product, search, and reviews are 5 credits. Taxonomy and stores are 1. Cache hits are free.
curl "https://www.socialcrawl.dev/v1/sephora/product?product_id=P427414" \
-H "x-api-key: sc_your_api_key_here"curl "https://www.socialcrawl.dev/v1/sephora/search?query=moisturizer" \
-H "x-api-key: sc_your_api_key_here"Same key as the rest of the catalog
Endpoints
What data does the Sephora API return?
Every endpoint returns structured JSON in a unified envelope. Computed fields such as engagement rate and content category are included only where the endpoint supports them and the required source inputs are present.
ProductGet a Sephora product by id or URLReviewsGet Sephora product reviewsSearchSearch Sephora products by keywordSearch SuggestionsGet Sephora search suggestionsCategoryBrowse Sephora products in a categoryCategoriesList Sephora root categoriesCategory DataGet a Sephora category and its childrenBrandsList Sephora brandsBrand ProductsList Sephora products for a brandStoresFind Sephora stores near a coordinateAvailabilityGet Sephora in-store availability for a sku
FAQ
Have a question? We got answers
Find answers to frequently asked questions about SocialCrawl's API, pricing, and capabilities.
Contact usHow much does the Sephora API cost?
Sephora endpoints are billed per call in credits: standard endpoints cost 1 credit, advanced 5, and premium 10. On Sephora that works out to between 1 and 5 credits per call. Every account starts with 100 free credits, and there is no subscription. You only pay for the calls you make.
Is scraping Sephora data legal?
SocialCrawl returns publicly available Sephora data and does not access private or login-gated content. Whether scraping fits your project depends on your use case and jurisdiction. You are responsible for complying with Sephora's terms of service and applicable data-protection laws such as GDPR and CCPA. This is general information, not legal advice.
Sephora scraping API vs the official Sephora API: what's the difference?
With SocialCrawl there is no app review or approval queue. Sign up and call Sephora endpoints immediately with a single x-api-key. Responses share one unified schema with every other SocialCrawl platform, and credit-based pricing replaces per-platform quotas. Official APIs are still the right choice for posting and other write actions: SocialCrawl is read-only data.