Looking for the overview — what this API returns, what it costs, and a call you can run without a key? See the Macy's US product, price, promotion and UPC-level stock data API page →

E-commerce & Marketplaces

Macy's US product, price, promotion and UPC-level stock data API & Scraper

Macy's US product, price, promotion and UPC-level stock data API returns live Macy's US product, price, promotion and UPC-level stock data data as clean JSON for macy's us product, price, promotion and upc-level stock data The primary endpoint, search, returns total (the retailer's own count), product_ids[], products[] with id and url, page, page_size (read from the answer, 60 on every full page….

6 actionsLive JSON1,000 free credits$0.67–$1.50 / 1,000 creditsMCP-ready

Get a free key Open in playground

🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.

Developers reach for it when they need to track product listings, prices, availability, variants and reviews without maintaining one-off scraping code or separate API contracts. If you were about to build or fix a Macy's US product, price, promotion and UPC-level stock data scraper, this API is the maintained alternative — it returns the same data as clean JSON, with the proxies, rotation and anti-bot handling already solved. This page covers the live example, request shape, response shape and available actions: search, product/detail, products/batch, product/reviews. Every request uses the same ReefAPI envelope, one API key and one shared credit pool, so it fits alongside the rest of your data stack.

Live example

Real request and response JSON

Captured from the indexed primary action, search, on Oct 3, 2026, 12:17 PM UTC.

Captured request

{
  "method": "POST",
  "url": "https://api.reefapi.com/macys/v1/search",
  "headers": {
    "x-api-key": "$REEF_KEY",
    "content-type": "application/json"
  },
  "body": {
    "query": "nike air max"
  }
}

Captured response

{
  "ok": true,
  "meta": {
    "api": "macys",
    "endpoint": "search",
    "mode": "live",
    "latency_ms": 2226.1,
    "record_count": 60,
    "bytes": 1442690,
    "cache_hit": false,
    "upstream_requests": 1,
    "charged_credits": 3,
    "version": "1.0.0",
    "request_id": "555b7560511840df",
    "queue_ms": 1
  },
  "data": {
    "query": "nike air max",
    "category_id": null,
    "total": 165,
    "returned_count": 60,
    "product_ids": [
      "26168414",
      "27616919",
      "25263796"
    ],
    "products": [
      {
        "id": "26168414",
        "url": "https://www.macys.com/shop/product/?ID=26168414"
      },
      {
        "id": "27616919",
        "url": "https://www.macys.com/shop/product/?ID=27616919"
      },
      {
        "id": "25263796",
        "url": "https://www.macys.com/shop/product/?ID=25263796"
      }
    ],
    "page": 1,
    "page_size": 60,
    "last_page": 3,
    "page_clamped": false,
    "has_more": true,
    "facets": [
      {
        "key": "UPC_BOPS_PURCHASABLE",
        "label": "Pick Up In-Store",
        "kind": "MULTISELECTDEFAULT",
        "values": [
          {
            "value": "[trimmed-depth]",
            "label": "[trimmed-depth]",
            "count": "[trimmed-depth]",
            "path": "[trimmed-depth]"
          }
        ]
      },
      {
        "key": "GENDER",
        "label": "Gender",
        "kind": "MULTISELECTDEFAULT",
        "values": [
          {
            "value": "[trimmed-depth]",
            "label": "[trimmed-depth]",
            "count": "[trimmed-depth]",
            "path": "[trimmed-depth]"
          },
          {
            "value": "[trimmed-depth]",
            "label": "[trimmed-depth]",
            "count": "[trimmed-depth]",
            "path": "[trimmed-depth]"
          },
          {
            "value": "[trimmed-depth]",
            "label": "[trimmed-depth]",
            "count": "[trimmed-depth]",
            "path": "[trimmed-depth]"
          }
        ]
      },
      {
        "key": "PRODUCT_DEPARTMENT",
        "label": "Item Type",
        "kind": "MULTISELECTDEFAULT",
        "values": [
          {
            "value": "[trimmed-depth]",
            "label": "[trimmed-depth]",
            "count": "[trimmed-depth]",
            "path": "[trimmed-depth]"
          },
          {
            "value": "[trimmed-depth]",
            "label": "[trimmed-depth]",
            "count": "[trimmed-depth]",
            "path": "[trimmed-depth]"
          },
          {
            "value": "[trimmed-depth]",
            "label": "[trimmed-depth]",
            "count": "[trimmed-depth]",
            "path": "[trimmed-depth]"
          }
        ]
      }
    ],
    "facets_are_filters": false,
    "facet_note": "Facets are reported so you can see how the retailer segments this result. They are not accepted as filters on this endpoint, because a filter we cannot show biting is a filter we will not publish.",
    "resolved_path": "/shop/search",
    "resolved_query": "keyword=nike%20air%20max",
    "resolve_with": "product/detail for one id, products/batch for up to 50 ids in one call",
    "past_last_page": false
  }
}

Actions

What the Macy's US product, price, promotion and UPC-level stock data API does

Action	Description	Concrete use case	Key params
search	Search the US catalogue by keyword, or list a whole category by its id. Returns the retailer's own result total, the product ids on the page, and the facets it offers for that result. Pages are real: page 1, 2 and 3 of a result are different products, and one page past the end the source stops publishing a grid, which is reported as past_last_page so a paging loop has a stop condition. Search answers with the retailer's own result count and the product ids on the page; turn those ids into full records with products/batch (up to 50 per call) or product/detail.	Pricing teams call search to search the US catalogue by keyword, or list a whole category by its id.	query, category_id, page
product/detail	Full published record for one Macy's product: brand, description, the whole price band with percent off and sale end date, promotions with their legal text, the category path, review summary, and one row per orderable variant with its 12-digit UPC, stock, shipping fees and delivery days.	Marketplace operators call product/detail to get full published record for one Macy's product.	id, fields
products/batch	Price, promotion, stock and UPC data for up to 50 products in ONE upstream call. The multi-id form of the source does not publish the category path, the review summary or the loyalty-card offer; those three fields come back null and are named in omitted_fields. Ids with no published product are returned in missing_ids rather than silently dropped.	Catalog enrichment teams call products/batch to get price, promotion, stock and UPC data for up to 50 products in ONE upstream call.	ids
product/reviews	A page of published customer reviews for one product, with rating, title, body, author nickname and location, helpful votes and whether the review was incentivised or syndicated.	Retail analysts call product/reviews to get a page of published customer reviews for one product, with rating, title, body, author nickna….	id, limit, offset
products/list	Walk the retailer's own published product feed to discover product ids and URLs. Measured 2026-10-03: 1,121,654 product entries across 23 shards. Use this when you want the whole catalogue rather than a keyword slice.	Pricing teams call products/list to get walk the retailer's own published product feed to discover product ids and URLs.	shard, limit, page
categories	The retailer's published category and brand-page list with ids and URLs, optionally narrowed by a text match on the category path. Category ids are the ids that appear as category_id on a product.	Marketplace operators call categories to get the retailer's published category and brand-page list with ids and URLs, optionally narrowed….	name_contains, limit, page

Code samples

Call search from your stack

curl -X POST https://api.reefapi.com/macys/v1/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nike air max"}'

import requests

r = requests.post(
    "https://api.reefapi.com/macys/v1/search",
    headers={"x-api-key": REEF_KEY},
    json={
  "query": "nike air max"
},
)
print(r.json()["data"])

const res = await fetch("https://api.reefapi.com/macys/v1/search", {
  method: "POST",
  headers: {
    "x-api-key": process.env.REEF_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
  "query": "nike air max"
}),
});
const { ok, data, meta, error } = await res.json();

MCP one-liner

Ask your MCP-connected assistant: call reefapi.macys.search with {"query":"nike air max"}.

Use cases

Who uses this API and why

Pricing teams use Macy's US product, price, promotion and UPC-level stock data to search the US catalogue by keyword, or list a whole category by its id.
Marketplace operators use Macy's US product, price, promotion and UPC-level stock data to get full published record for one Macy's product.
Catalog enrichment teams use Macy's US product, price, promotion and UPC-level stock data to get price, promotion, stock and UPC data for up to 50 products in ONE upstream call.
Retail analysts use Macy's US product, price, promotion and UPC-level stock data to get a page of published customer reviews for one product, with rating, title, body, author nickna….
Pricing teams use Macy's US product, price, promotion and UPC-level stock data to get walk the retailer's own published product feed to discover product ids and URLs.

FAQ

Questions developers ask before integrating

What is the Macy's US product, price, promotion and UPC-level stock data API?

Macy's US product, price, promotion and UPC-level stock data API is a ReefAPI endpoint group for macy's us product, price, promotion and upc-level stock data It returns live JSON through POST requests under /macys/v1.

Is the Macy's US product, price, promotion and UPC-level stock data API free to try?

Yes. ReefAPI starts with 1,000 free credits, no card required. Macy's US product, price, promotion and UPC-level stock data calls use the same shared credit balance as every other ReefAPI engine.

Do I need a Macy's US product, price, promotion and UPC-level stock data login or account?

No login to Macy's US product, price, promotion and UPC-level stock data is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.

How fresh is the Macy's US product, price, promotion and UPC-level stock data data?

The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.

How many credits does the Macy's US product, price, promotion and UPC-level stock data API use?

Macy's US product, price, promotion and UPC-level stock data actions currently cost 1-3 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.

Can I call Macy's US product, price, promotion and UPC-level stock data from an AI assistant or MCP client?

Yes. Connect ReefAPI once through MCP and your assistant can call macys actions with the same key, credit pool and JSON envelope used by normal REST requests.

Is the Macy's US product, price, promotion and UPC-level stock data API a Macy's US product, price, promotion and UPC-level stock data scraper?

It is the managed alternative to a DIY Macy's US product, price, promotion and UPC-level stock data scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same macy's us product, price, promotion and upc-level stock data back as clean JSON.

Why does my Macy's US product, price, promotion and UPC-level stock data scraper keep getting blocked?

Most Macy's US product, price, promotion and UPC-level stock data scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked calls are free.

docs / macys

Macy's US product, price, promotion and UPC-level stock data

base /macys/v16 endpoints

post/macys/v1/search3 credits

Search the US catalogue by keyword, or list a whole category by its id. Returns the retailer's own result total, the product ids on the page, and the facets it offers for that result. Pages are real: page 1, 2 and 3 of a result are different products, and one page past the end the source stops publishing a grid, which is reported as past_last_page so a paging loop has a stop condition. Search answers with the retailer's own result count and the product ids on the page; turn those ids into full records with products/batch (up to 50 per call) or product/detail.

Parameter		Allowed / range	Description
query	optional	—	Keyword to search the US catalogue for. Exactly one of query or category_id is required. They cannot be combined: the source keeps the keyword and throws the category away, so the call is refused instead of quietly answering a different question.
category_id	optional	—	A numeric category id from the categories action, to list that whole category instead of searching a keyword. Exactly one of query or category_id is required. Narrowing is real and measured: 18,472 rows for women's dresses, 4,616 for mini dresses, 307 for corset dresses.
page = 1	optional	1–500	One-based result page. The answer carries total, page_size and last_page so a paging loop has a real stop condition.

Try in playground →

post/macys/v1/product/detail2 credits

Full published record for one Macy's product: brand, description, the whole price band with percent off and sale end date, promotions with their legal text, the category path, review summary, and one row per orderable variant with its 12-digit UPC, stock, shipping fees and delivery days.

Parameter		Allowed / range	Description
id	required	—	Macy's numeric product id, or a macys.com product URL carrying ?ID=. Ids come from products/list, from product/detail URLs, or from your own records.
fields = full	optional	full · core	full returns the review summary and the loyalty-card offer as well. core asks the retailer for its compact form: identical prices, UPCs, per-variant stock, shipping fees, delivery days, promotions, images and category path, measured 11-73 % smaller.

Try in playground →

post/macys/v1/products/batch3 credits

Price, promotion, stock and UPC data for up to 50 products in ONE upstream call. The multi-id form of the source does not publish the category path, the review summary or the loyalty-card offer; those three fields come back null and are named in omitted_fields. Ids with no published product are returned in missing_ids rather than silently dropped.

Parameter		Allowed / range	Description
ids	required	—	Two to 50 Macy's product ids. A comma-separated string works too. Duplicates are collapsed and ids with no published product are returned in missing_ids.

Try in playground →

post/macys/v1/product/reviews1 credit

A page of published customer reviews for one product, with rating, title, body, author nickname and location, helpful votes and whether the review was incentivised or syndicated.

Parameter		Allowed / range	Description
id	required	—	Macy's numeric product id, or a macys.com product URL carrying ?ID=. Ids come from products/list, from product/detail URLs, or from your own records.
limit = 20	optional	1–50	Reviews per page. Values outside 1-50 are clamped, not rejected.
offset = 0	optional	0–10000	Reviews to skip. The authoritative review total is reviews_summary.review_count on product/detail.

Try in playground →

post/macys/v1/products/list3 credits

Walk the retailer's own published product feed to discover product ids and URLs. Measured 2026-10-03: 1,121,654 product entries across 23 shards. Use this when you want the whole catalogue rather than a keyword slice.

Parameter		Allowed / range	Description
shard = aa	optional	aa · ab · ac · ad · ae · af · ag · ah · ai · aj · ak · al · am · an · ao · ap · aq · ar · as · at · au · av · aw	Which shard of the retailer's published product feed to read. Twenty-two shards hold 50,000 products each and one holds the remainder; the response names every shard that exists today.
limit = 200	optional	1–1000	Products per page out of the shard. Clamped to 1-1000.
page = 1	optional	1–50000	One-based page within the shard. A page past the end is clamped and page_clamped is set, so a paging loop cannot spin forever.

Try in playground →

post/macys/v1/categories2 credits

The retailer's published category and brand-page list with ids and URLs, optionally narrowed by a text match on the category path. Category ids are the ids that appear as category_id on a product.

Parameter		Allowed / range	Description
name_contains	optional	—	Keep only categories whose published path contains this text, case-insensitive. The answer always carries both the feed total and the matched total. This is NOT a product keyword search.
limit = 100	optional	1–1000	Categories per page. Clamped to 1-1000.
page = 1	optional	1–1000	One-based page. A page past the end is clamped.

Try in playground →

Example request · search

curl -X POST https://api.reefapi.com/macys/v1/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nike air max"}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}

Built for volume

5M+ requests a day

Measured at 60 requests a second across the fleet, with no central bottleneck. Volume pricing is on request, and per-key limits are raised for high-volume accounts.

Missing a source?

We build it

Tell us a site we do not cover yet and it becomes an engine. A customer asked for bestprice.gr on a Sunday and it was in the catalog the next day.

Support

2 minute median reply

Median time from a question in the live chat to the first answer, measured across every answered conversation. Setup help included, no support tier to buy.

One key, one balance

Every API included

No per-site plans and no separate subscriptions. One key and one credit pool across the whole catalog, so adding a source costs nothing up front.

Planning something large? Tell us the volume and the sources and we will come back with what it costs and what we would have to build.

Comparing scraping APIs?ReefAPI vs Apify Trendyol actors ReefAPI vs Retailed ReefAPI vs DataForSEO