# H&M API scraper — hm.com in 41 markets: search products, read the full article with the regular, sale and H&M member prices kept apart, every colour with its own prices, sizes in stock and few-left flags, composition, materials, care and country of production, ratings; browse categories, suggestions and live size availability. No account, no browser.

> Search H&M in any of its 41 markets by keyword. Each product comes with the price a shopper pays, the regular price when a sale price is running, the H&M member price kept separate, currency, every colour, sizes with in-stock flags, markers and availability. Sort by newest or price; filter by department, sale, colour or material. Misspellings H&M corrects are reported in matched_query.
> ReefAPI engine `hm` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/hm/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /hm/v1/search — 1 credit
Search H&M in any of its 41 markets by keyword. Each product comes with the price a shopper pays, the regular price when a sale price is running, the H&M member price kept separate, currency, every colour, sizes with in-stock flags, markers and availability. Sort by newest or price; filter by department, sale, colour or material. Misspellings H&M corrects are reported in matched_query.

**Parameters:**
- `query` (string, required) — Words a shopper would type on H&M, in the market's language.
- `country` (enum, optional, default "us") — The H&M market. Prices, currency, language and assortment follow it. A product URL's own market is used when this is not given. [one of: us, ca, mx, gb, ie, de, at, ch, fr, be, nl, es, pt, it, gr, se, no, dk, fi, pl, cz, sk, hu, ro, bg, rs, ua, tr, il, in, jp, kr, hk, asia1, asia3, sg, my, ph, vn, au, eur]
- `language` (enum, optional) — Only for markets with several languages: ca (en, fr), ch (de, fr, it), be (nl, fr), fi (fi, sv), hk / asia1 / asia3 (en, zh). Defaults to the market's first language. [one of: bg, cs, da, de, el, en, es, fi, fr, he, hu, it, ja, ko, nl, no, pl, pt, ro, sk, sr, sv, tr, uk, vi, zh]
- `page` (integer, optional, default 1) — Result page, from 1.
- `page_size` (integer, optional, default 36) — Products per page (H&M's own page shows 36; the service allows up to 72).
- `sort` (enum, optional, default "relevance") — H&M's own sort orders. [one of: relevance, newest, price_asc, price_desc]
- `department` (string, optional) — Only one department, by the id `filters_available.departments` lists (ladies_all, men_all, kids_all, sale, …).
- `sale_only` (boolean, optional, default false) — true: only products with a sale (red) price.
- `color` (string, optional) — Only one colour, by the id `filters_available.colors` lists (black_000000).
- `material` (string, optional) — Only one material, spelled as `filters_available.materials` lists it.
- `max_rotations` (integer, optional, default 3) — Attempts per upstream request before giving up (each on a fresh exit).

**Returns:** results[]{article_code, product_code, name, brand, url, image, model_image, images[], price, regular_price, on_sale, discount_percent, member_price, price_formatted, price_range{min, max}, currency, color_name, color_hex, color_shades[], colors[]{article_code, color_name, hex, url, image}, color_count, sizes[]{size_code, label, in_stock}, sizes_in_stock, availability, coming_soon, online, pre_shopping, new_arrival, multipack, external_brand, markers[]{text, type}, main_category, has_video}, count, page, page_size, total_results, total_pages, has_more, page_out_of_range, country, language, locale, currency, query, matched_query, did_you_mean[], related_searches[], query_blocked, sort_applied, filters_applied{}, filters_available{departments[], colors[], materials[], sale{}, price_range{}}

**Example request body:**
```json
{
  "query": "dress"
}
```

### POST /hm/v1/product/detail — 2 credits
The full H&M article by article code, product code or URL: name, brand, category and breadcrumb, description and details, the price with the regular price and discount on sale, the member price apart, H&M's legal price note, currency, colour, images, every size with in-stock and few-left flags, composition per garment part, preferred materials, recycled share, country of production, care instructions, model height and size worn, rating and review count with the page's review sample, and every other colour of the product with its own prices and sizes.

**Parameters:**
- `article_code` (string, required) — An H&M article code (10 digits = product + colour, as in a product URL), a 7-digit product code (resolved to its default colour) or an hm.com product URL.
- `country` (enum, optional, default "us") — The H&M market. Prices, currency, language and assortment follow it. A product URL's own market is used when this is not given. [one of: us, ca, mx, gb, ie, de, at, ch, fr, be, nl, es, pt, it, gr, se, no, dk, fi, pl, cz, sk, hu, ro, bg, rs, ua, tr, il, in, jp, kr, hk, asia1, asia3, sg, my, ph, vn, au, eur]
- `language` (enum, optional) — Only for markets with several languages: ca (en, fr), ch (de, fr, it), be (nl, fr), fi (fi, sv), hk / asia1 / asia3 (en, zh). Defaults to the market's first language. [one of: bg, cs, da, de, el, en, es, fi, fr, he, hu, it, ja, ko, nl, no, pl, pt, ro, sk, sr, sv, tr, uk, vi, zh]
- `max_rotations` (integer, optional, default 3) — Attempts per upstream request before giving up (each on a fresh exit).

**Returns:** product{article_code, product_code, name, brand, url, category, product_type, main_category, breadcrumb[]{name, url}, audience, description, details[], attributes{}, concept[], price, regular_price, on_sale, discount_percent, member_price, price_type ('sale'|'member'|null), price_note, currency, color{name, hex, color_code}, images[]{url, type, alt}, sizes[]{size_code, size, label, in_stock, few_left}, sizes_in_stock, available, composition[]{part, materials[]{name, percent}}, composition_text[], preferred_materials[]{name, percent}, material_details[]{name, description}, recycled_materials_percent, country_of_production[], care_instructions[], model_height, model_size_worn, coming_soon, new_arrival, in_store_assortment, markers[], rating, review_count, rating_scale, reviews_sample[]{rating, text, date, dimensions[]}, variants[]{article_code, color_name, hex, color_code, url, image, price, regular_price, on_sale, discount_percent, member_price, price_type, price_note, sizes[], sizes_in_stock, available, coming_soon, new_arrival}, variant_count, delivery_note, availability_source}, country, language, locale

**Example request body:**
```json
{
  "article_code": "1323075003",
  "country": "fr"
}
```

### POST /hm/v1/category — 2 credits
Every product on one H&M category page (a department, a product type, a sale page), paged and sorted, with the same rows as search. Pass the category URL or path, or the category_id + page_id a previous call returned.

**Parameters:**
- `category` (string, optional) — An H&M category page: its URL or its path (/ladies/shop-by-product/dresses.html). `breadcrumb` on any product lists them.
- `category_id` (string, optional) — With page_id: the listing ids a previous category call returned (skips reading the category page).
- `page_id` (string, optional) — With category_id: the listing ids a previous category call returned.
- `country` (enum, optional, default "us") — The H&M market. Prices, currency, language and assortment follow it. A product URL's own market is used when this is not given. [one of: us, ca, mx, gb, ie, de, at, ch, fr, be, nl, es, pt, it, gr, se, no, dk, fi, pl, cz, sk, hu, ro, bg, rs, ua, tr, il, in, jp, kr, hk, asia1, asia3, sg, my, ph, vn, au, eur]
- `language` (enum, optional) — Only for markets with several languages: ca (en, fr), ch (de, fr, it), be (nl, fr), fi (fi, sv), hk / asia1 / asia3 (en, zh). Defaults to the market's first language. [one of: bg, cs, da, de, el, en, es, fi, fr, he, hu, it, ja, ko, nl, no, pl, pt, ro, sk, sr, sv, tr, uk, vi, zh]
- `page` (integer, optional, default 1) — Result page, from 1.
- `page_size` (integer, optional, default 36) — Products per page (H&M's own page shows 36; the service allows up to 72).
- `sort` (enum, optional, default "relevance") — H&M's own sort orders. [one of: relevance, newest, price_asc, price_desc]
- `max_rotations` (integer, optional, default 3) — Attempts per upstream request before giving up (each on a fresh exit).

**Returns:** results[]{article_code, product_code, name, brand, url, image, model_image, images[], price, regular_price, on_sale, discount_percent, member_price, price_formatted, price_range{min, max}, currency, color_name, color_hex, color_shades[], colors[]{article_code, color_name, hex, url, image}, color_count, sizes[]{size_code, label, in_stock}, sizes_in_stock, availability, coming_soon, online, pre_shopping, new_arrival, multipack, external_brand, markers[]{text, type}, main_category, has_video}, count, page, page_size, total_results, total_pages, has_more, page_out_of_range, country, language, locale, currency, category{url, title, category_id, page_id}, sort_applied

### POST /hm/v1/search/suggest — 1 credit
H&M's search-box suggestions for what a shopper has typed: suggested searches and linked content pages, in the market's language.

**Parameters:**
- `query` (string, required) — What a shopper has typed so far.
- `country` (enum, optional, default "us") — The H&M market. Prices, currency, language and assortment follow it. A product URL's own market is used when this is not given. [one of: us, ca, mx, gb, ie, de, at, ch, fr, be, nl, es, pt, it, gr, se, no, dk, fi, pl, cz, sk, hu, ro, bg, rs, ua, tr, il, in, jp, kr, hk, asia1, asia3, sg, my, ph, vn, au, eur]
- `language` (enum, optional) — Only for markets with several languages: ca (en, fr), ch (de, fr, it), be (nl, fr), fi (fi, sv), hk / asia1 / asia3 (en, zh). Defaults to the market's first language. [one of: bg, cs, da, de, el, en, es, fi, fr, he, hu, it, ja, ko, nl, no, pl, pt, ro, sk, sr, sv, tr, uk, vi, zh]
- `max_rotations` (integer, optional, default 3) — Attempts per upstream request before giving up (each on a fresh exit).

**Returns:** suggestions[]{text}, content[]{title, url}, count, query, country, language, locale

**Example request body:**
```json
{
  "query": "dress"
}
```

### POST /hm/v1/product/availability — 1 credit
Live size availability for every colour of one H&M product in one market: which sizes can be ordered and which H&M flags as few pieces left. One small call — for stock monitoring.

**Parameters:**
- `article_code` (string, required) — An H&M article code (10 digits = product + colour, as in a product URL), a 7-digit product code (resolved to its default colour) or an hm.com product URL.
- `country` (enum, optional, default "us") — The H&M market. Prices, currency, language and assortment follow it. A product URL's own market is used when this is not given. [one of: us, ca, mx, gb, ie, de, at, ch, fr, be, nl, es, pt, it, gr, se, no, dk, fi, pl, cz, sk, hu, ro, bg, rs, ua, tr, il, in, jp, kr, hk, asia1, asia3, sg, my, ph, vn, au, eur]
- `language` (enum, optional) — Only for markets with several languages: ca (en, fr), ch (de, fr, it), be (nl, fr), fi (fi, sv), hk / asia1 / asia3 (en, zh). Defaults to the market's first language. [one of: bg, cs, da, de, el, en, es, fi, fr, he, hu, it, ja, ko, nl, no, pl, pt, ro, sk, sr, sv, tr, uk, vi, zh]
- `max_rotations` (integer, optional, default 3) — Attempts per upstream request before giving up (each on a fresh exit).

**Returns:** product_code, articles[]{article_code, sizes_in_stock[]{size_code, size}, few_left[]{size_code, size}}, article_count, sizes_in_stock, sizes_few_left, country, locale

**Example request body:**
```json
{
  "article_code": "1323075003"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=hm
- Human docs page: https://reefapi.com/docs/hm
- Overview page: https://reefapi.com/hm-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt