Shop APIshop.app ↗
Access Shop.app product listings, merchant profiles, categories, and homepage featured items via 6 structured endpoints. Includes prices, ratings, and reviews.
What is the Shop API?
The Shop.app API exposes 6 endpoints for retrieving product data, merchant profiles, shopping categories, and autocomplete suggestions from shop.app. With get_product_details you get full pricing (including discount deltas via original_price), multiple product images, and merchant identity in a single call. Other endpoints cover paginated merchant catalogs, top-level category trees, homepage carousel items, and search autocomplete for both query strings and shop matches.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/5dd62abe-8dc5-4896-99ae-78ddfd844b61/get_homepage_featured_products' \ -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 shop-app-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.
from parse_apis.shop_app_api import ShopApp, Product, ProductSummary, Merchant, MerchantProduct, ProductImage, Category, Suggestion, SuggestedShop, ReviewAnalytics, ProductNotFound
client = ShopApp()
# Discover featured products from the homepage
for product in client.productsummaries.featured():
print(product.title, product.category, product.rating, product.review_count)
# Drill into full details
details = product.details()
print(details.price, details.original_price, details.merchant.name)
break
# Search for suggestions and explore a merchant
for suggestion in client.suggestions.search(query="nike"):
if suggestion.shop is not None:
print(suggestion.shop.name, suggestion.shop.handle, suggestion.shop.rating)
# Construct merchant from ID and browse products
merchant = client.merchant(id=suggestion.shop.id)
for item in merchant.products(first=10):
print(item.title, item.slug, item.price)
for img in item.images:
print(img.url)
break
# Browse all categories
for cat in client.categories.list():
print(cat.name, cat.has_children, cat.id)
Retrieves featured products from the shop.app homepage hero carousel. Returns up to 10 products across categories (general, beauty, fashion). No parameters needed. Each product includes basic info suitable for drilling into details via get_product_details.
No input parameters required.
{
"type": "object",
"fields": {
"products": "array of product objects with id, title, slug, category, image_url, rating, review_count"
},
"sample": {
"data": {
"products": [
{
"id": "4131300606034",
"slug": "cookware-set",
"title": "Cookware Set",
"rating": 4.8,
"category": "general",
"image_url": "https://cdn.shopify.com/s/files/1/0258/6273/3906/files/Cookware_Set.jpg",
"review_count": 39164
}
]
},
"status": "success"
}
}About the Shop API
Products and Pricing
get_product_details takes a product_id and product_slug — both available from get_homepage_featured_products or get_merchant_products — and returns a full product record: price, original_price (non-null when a discount is active), an images array, rating, review_count, and a merchant object containing the merchant's id, name, and handle. The images array typically holds multiple angles or variant shots. get_homepage_featured_products requires no inputs and returns up to 10 products from the homepage hero carousel, each with id, slug, category, image_url, rating, and review_count — useful for monitoring what Shop.app is currently surfacing.
Merchant Catalog and Profiles
get_merchant_info accepts a merchant handle and returns the merchant's numeric id, name, shopifyId, websiteUrl, defaultHandle, and productReviewAnalytics (which includes totalProductReviews and averageRating). That id can then be passed as broker_id to get_merchant_products, which returns a paginated list of the merchant's products sorted by most sales. Pagination uses a cursor pattern: pass after (the pageInfo.endCursor from the previous page) alongside first to page through results. Each product node includes id, title, slug, price, originalPrice, images, and reviewAnalytics.
Categories and Search
list_categories returns all top-level categories on shop.app, each with a name, a Shopify GID-format id, a hasChildren boolean indicating whether subcategories exist, and a path array of GIDs representing its position in the taxonomy. get_search_autocomplete takes a query string prefix and returns mixed suggestions: entries with type: 'query' are keyword completions, while type: 'shop' entries include a nested shop object with the merchant's id, name, handle, and rating — handy for resolving a partial merchant name into a handle for subsequent calls.
The Shop API is a managed, monitored endpoint for shop.app — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when shop.app 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 shop.app 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 drops on specific products by comparing
pricevsoriginal_pricefromget_product_details - Build a merchant intelligence dashboard using
get_merchant_infofor ratings andget_merchant_productsfor full catalog size viatotalCount - Monitor homepage merchandising trends by polling
get_homepage_featured_productsand logging which products and categories appear - Resolve partial brand names to merchant handles using
get_search_autocompletebefore fetching full profiles - Enumerate all shop.app top-level categories and their Shopify GID identifiers with
list_categories - Paginate through a merchant's entire product catalog sorted by sales rank using
get_merchant_productscursor pagination - Aggregate review counts and average ratings across merchants using
productReviewAnalyticsfromget_merchant_info
| 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 Shop.app have an official developer API?+
What does get_search_autocomplete return beyond keyword suggestions?+
type field. Entries with type: 'query' are keyword completions for the query prefix. Entries with type: 'shop' include a nested shop object containing the merchant's id, name, handle, and rating, letting you resolve a partial merchant name into a handle you can pass directly to get_merchant_info or get_merchant_products.Does list_categories return subcategory trees, or only top-level categories?+
hasChildren boolean that indicates whether subcategories exist beneath it, and a path array of GIDs showing its taxonomy position — but child categories are not expanded inline. The API currently covers top-level browsing. You can fork it on Parse and revise to add a subcategory drill-down endpoint.Is product inventory or stock status available from any endpoint?+
How does pagination work in get_merchant_products?+
pageInfo object with hasNextPage (boolean) and endCursor (string). To fetch the next page, pass the endCursor value as the after parameter in your next request, along with first to control page size. The totalCount field tells you the merchant's full product count regardless of page.