{"openapi":"3.0.3","info":{"title":"H&M API (ReefAPI)","version":"0.1.0","description":"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. Call POST /hm/v1/{action} with an x-api-key header; every response is the { ok, data, meta, error } envelope.","contact":{"name":"ReefAPI","url":"https://reefapi.com/hm-api","email":"support@reefapi.com"},"license":{"name":"ReefAPI Terms","url":"https://reefapi.com/terms"},"termsOfService":"https://reefapi.com/terms"},"externalDocs":{"description":"H&M API documentation","url":"https://reefapi.com/docs/hm"},"servers":[{"url":"https://api.reefapi.com"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"hm","description":"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."}],"paths":{"/hm/v1/search":{"post":{"operationId":"hm_search","summary":"Search H&M in any of its 41 markets by keyword","description":"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.","tags":["hm"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"linen shirt","description":"Words a shopper would type on H&M, in the market's language."},"country":{"type":"string","enum":["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"],"default":"us","example":"gb","description":"The H&M market. Prices, currency, language and assortment follow it. A product URL's own market is used when this is not given."},"language":{"type":"string","enum":["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"],"example":"fr","description":"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."},"page":{"type":"integer","minimum":1,"maximum":500,"default":1,"description":"Result page, from 1."},"page_size":{"type":"integer","minimum":1,"maximum":72,"default":36,"description":"Products per page (H&M's own page shows 36; the service allows up to 72)."},"sort":{"type":"string","enum":["relevance","newest","price_asc","price_desc"],"default":"relevance","example":"price_asc","description":"H&M's own sort orders."},"department":{"type":"string","example":"ladies_all","description":"Only one department, by the id `filters_available.departments` lists (ladies_all, men_all, kids_all, sale, …)."},"sale_only":{"type":"boolean","default":false,"description":"true: only products with a sale (red) price."},"color":{"type":"string","example":"black_000000","description":"Only one colour, by the id `filters_available.colors` lists (black_000000)."},"material":{"type":"string","example":"Linen","description":"Only one material, spelled as `filters_available.materials` lists it."},"max_rotations":{"type":"integer","minimum":1,"maximum":6,"default":3,"description":"Attempts per upstream request before giving up (each on a fresh exit)."}},"required":["query"]},"example":{"query":"dress"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/hm/v1/product/detail":{"post":{"operationId":"hm_product_detail","summary":"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,","description":"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.","tags":["hm"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"article_code":{"type":"string","example":"1323075003","description":"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":{"type":"string","enum":["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"],"default":"us","example":"gb","description":"The H&M market. Prices, currency, language and assortment follow it. A product URL's own market is used when this is not given."},"language":{"type":"string","enum":["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"],"example":"fr","description":"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."},"max_rotations":{"type":"integer","minimum":1,"maximum":6,"default":3,"description":"Attempts per upstream request before giving up (each on a fresh exit)."}},"required":["article_code"]},"example":{"article_code":"1323075003","country":"fr"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":2}},"/hm/v1/category":{"post":{"operationId":"hm_category","summary":"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","description":"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.","tags":["hm"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","example":"https://www2.hm.com/en_gb/ladies/shop-by-product/dresses.html","description":"An H&M category page: its URL or its path (/ladies/shop-by-product/dresses.html). `breadcrumb` on any product lists them."},"category_id":{"type":"string","example":"LADIES_SHOPBYPRODUCT : DRESSES_DRESSES : VIEWALL_VIEW_ALL","description":"With page_id: the listing ids a previous category call returned (skips reading the category page)."},"page_id":{"type":"string","example":"/ladies/shop-by-product/dresses","description":"With category_id: the listing ids a previous category call returned."},"country":{"type":"string","enum":["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"],"default":"us","example":"gb","description":"The H&M market. Prices, currency, language and assortment follow it. A product URL's own market is used when this is not given."},"language":{"type":"string","enum":["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"],"example":"fr","description":"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."},"page":{"type":"integer","minimum":1,"maximum":500,"default":1,"description":"Result page, from 1."},"page_size":{"type":"integer","minimum":1,"maximum":72,"default":36,"description":"Products per page (H&M's own page shows 36; the service allows up to 72)."},"sort":{"type":"string","enum":["relevance","newest","price_asc","price_desc"],"default":"relevance","example":"price_asc","description":"H&M's own sort orders."},"max_rotations":{"type":"integer","minimum":1,"maximum":6,"default":3,"description":"Attempts per upstream request before giving up (each on a fresh exit)."}}},"example":{"category":"https://www2.hm.com/en_gb/ladies/shop-by-product/dresses.html"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":2}},"/hm/v1/search/suggest":{"post":{"operationId":"hm_search_suggest","summary":"H&M's search-box suggestions for what a shopper has typed: suggested searches and linked content pages, in the market's language.","description":"H&M's search-box suggestions for what a shopper has typed: suggested searches and linked content pages, in the market's language.","tags":["hm"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"lin","description":"What a shopper has typed so far."},"country":{"type":"string","enum":["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"],"default":"us","example":"gb","description":"The H&M market. Prices, currency, language and assortment follow it. A product URL's own market is used when this is not given."},"language":{"type":"string","enum":["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"],"example":"fr","description":"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."},"max_rotations":{"type":"integer","minimum":1,"maximum":6,"default":3,"description":"Attempts per upstream request before giving up (each on a fresh exit)."}},"required":["query"]},"example":{"query":"dress"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/hm/v1/product/availability":{"post":{"operationId":"hm_product_availability","summary":"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","description":"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.","tags":["hm"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"article_code":{"type":"string","example":"1323075003","description":"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":{"type":"string","enum":["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"],"default":"us","example":"gb","description":"The H&M market. Prices, currency, language and assortment follow it. A product URL's own market is used when this is not given."},"language":{"type":"string","enum":["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"],"example":"fr","description":"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."},"max_rotations":{"type":"integer","minimum":1,"maximum":6,"default":3,"description":"Attempts per upstream request before giving up (each on a fresh exit)."}},"required":["article_code"]},"example":{"article_code":"1323075003"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Envelope":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"data":{"description":"Action result (shape varies per action)"},"meta":{"type":"object","description":"api, endpoint, mode, latency_ms, record_count, completeness_pct"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}