Macys APImacys.com ↗
Access Macy's product catalog via API. Search products, browse category trees, and fetch detailed pricing, sizing, availability, and imagery for any item.
What is the Macys API?
The Macy's API exposes 4 endpoints for querying the full Macy's product catalog, covering search, category navigation, category browsing, and product detail retrieval. The search_products endpoint returns up to 20 products per query with name, brand, description, pricing, colors, sizes, availability, and imagery. Together the endpoints give structured access to the same catalog data shoppers see on macys.com.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/767f72c4-3498-4f8b-b11d-47cc123dc71b/get_category_navigation' \ -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 macys-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.
from parse_apis.macys_api import Macys, Product, NavigationCategory
client = Macys()
# Search for products by keyword
for product in client.products.search(query="handbags", limit=3):
print(product.id, product.detail.name, product.detail.brand.name)
print(product.pricing.price.tiered_price[0].values[0].formatted_value)
print(product.availability.available)
# Browse category products to get IDs
for pid in client.products.browse(category_id="55352", pathname="/shop/jewelry-watches/jewelry/fashion-jewelry", limit=5):
print(pid)
# Get navigation categories
nav = client.products.navigation()
for cat_id, category in nav.items():
print(category.id, category.text, category.category_page_type)
break
Retrieve the site menu structure including all main departments and subcategories with associated category IDs. Returns a flat map of category objects keyed by category ID. Each category includes id, text, url, parent info, children (if any), and categoryPageType. Use this to discover valid category_id and pathname values for the browse_category endpoint.
No input parameters required.
{
"type": "object",
"fields": {
"menu": "object mapping category IDs to category objects, each containing id, text, url, parent, children, and categoryPageType"
},
"sample": {
"data": {
"menu": {
"69963": {
"id": "69963",
"url": "/shop/home/furniture-mattress/entryway?id=69963&cm_sp=mew_navigation_shop-_-home_furnituremattresses-_-69963_entryway",
"text": "Entryway",
"title": "Entryway",
"value": "69963",
"parent": {
"id": "29391",
"text": "Furniture & Mattresses"
},
"categoryPageType": "Browse"
}
}
},
"status": "success"
}
}About the Macys API
Category Navigation and Browsing
The get_category_navigation endpoint returns the full Macy's site menu as a flat map keyed by category ID. Each entry includes id, text, url, parent, children, and categoryPageType, giving you a traversable tree of every department and subcategory. Once you have a category ID and pathname from this map, you can pass both to browse_category to list products in that category. browse_category returns total (the full product count), an array of product_ids for the current page, and a facets array describing available filter dimensions — each facet includes name, displayName, and its possible values.
Product Search and Detail
The search_products endpoint accepts a query string and an optional page_index. Each result object in the product array carries id, detail (name, description, brand), structured pricing, imagery, availability, and traits including colors and sizes. For bulk or targeted lookups, get_product_details accepts a single product ID or a comma-separated list and returns the same rich fields plus flags within detail and shipping information. Batching multiple IDs in one call reduces round trips when you already have IDs from browse_category.
Combining Endpoints
A typical workflow chains get_category_navigation → browse_category → get_product_details. First retrieve category IDs and pathnames, then page through product IDs in a category, then batch-fetch full detail objects. Alternatively, search_products short-circuits navigation by returning full product data directly from a keyword, useful when you know what item you want but not its category path.
The Macys API is a managed, monitored endpoint for macys.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when macys.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 macys.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?+
- Build a price comparison tool using pricing fields from
get_product_detailsacross multiple product IDs - Populate a category-tree UI by parsing the
childrenandparentfields fromget_category_navigation - Track in-stock availability changes across a product list using the
availabilityfield inget_product_details - Generate a product feed filtered by size or color using
traitsfromsearch_products - Audit category facets and filter dimensions across Macy's departments using the
facetsarray inbrowse_category - Sync Macy's product imagery URLs into an internal catalog using the
imageryfield returned by both search and detail endpoints - Monitor total product count per category over time using the
totalfield frombrowse_category
| 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 Macy's have an official developer API?+
What does `browse_category` return beyond product IDs?+
browse_category returns a total count of all products in the category, a paginated array of integer product_ids, and a facets array. Each facet object includes name, displayName, and an array of possible values, representing the filter dimensions available for that category (such as brand, color, or size). To get full product data, pass the returned IDs to get_product_details.Does the API return customer reviews or ratings for products?+
How does pagination work across endpoints?+
search_products and browse_category accept an optional page_index parameter for paginating results. browse_category also accepts products_per_page to control how many product IDs are returned per page. get_product_details does not paginate — it accepts a comma-separated list of IDs in a single call.Are sale prices and promotions included in the pricing fields?+
pricing object is returned for each product across search_products and get_product_details, but the exact sub-fields (such as original vs. sale price, or promotional flags) depend on what Macy's exposes per product. The detail object in get_product_details also includes a flags field that may surface promotional or sale indicators for a given item.