# H&M — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access H&M's product catalog, search, category navigation, sale and new-arrival listings, product details, similar-item recommendations, and US store locations.

**Category:** E-commerce | **Website:** [www2.hm.com/](https://www2.hm.com/) | **Docs:** [parse.bot/marketplace/0610bb3a-e08c-42b7-8063-ef15fefd7a1a/h-m-api](https://parse.bot/marketplace/0610bb3a-e08c-42b7-8063-ef15fefd7a1a/h-m-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_category_navigation

Fetch the full site navigation tree including all departments and subcategories. Returns hierarchical menu structure with nodeId, nodeName, href, and nested children for Women, Men, Kids, Baby, and other departments.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/get_category_navigation \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_new_arrivals

Fetch new arrivals for a category. Returns recently added products with pricing and availability. Uses the same listing mechanism as category pages but scoped to new arrivals sections.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | New arrivals category path (e.g. 'women/new-arrivals/view-all', 'men/new-arrivals/view-all'). |
| `page` | integer | No | Page number for pagination (1-based). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/get_new_arrivals \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","page":"<integer>"}'
```

### get_product_detail

Fetch product details including pricing, availability, color variants, and images for a given article code or product URL. Returns full variant information with all color options, stock states, and image galleries. Either article_code or url must be provided.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `article_code` | string | No | Article code (e.g. '0685816001', '1347416001'). Either article_code or url must be provided. |
| `url` | string | No | Full product URL (e.g. 'https://www2.hm.com/en_us/productpage.0685816001.html'). Either article_code or url must be provided. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/get_product_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"article_code":"<string>","url":"<string>"}'
```

### get_product_details_kr

Get full product details for a Korean H&M product including all color variants, size-level online availability, images with type labels, KRW prices (regular, current, member), and stock state. Either article_code or a Korean product URL must be provided. Makes up to 2 additional requests: one to fetch all color variants and one to check size-level availability.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `article_code` | string | No | 10-digit article code (e.g. '1309848011'). Either article_code or url must be provided. |
| `url` | string | No | Korean H&M product URL (must contain /ko_kr/). Either article_code or url must be provided. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/get_product_details_kr \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"article_code":"<string>","url":"<string>"}'
```

### get_product_listing

Fetch paginated product listings for a specific category path. Returns product hits with pricing, images, swatches, sizes, and pagination metadata. Each page returns up to 36 products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Category path (e.g. 'men/products/view-all', 'women/products/view-all', 'kids/girls/products/view-all'). |
| `page` | integer | No | Page number for pagination (1-based). |
| `sort` | string | No | Sort order for results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/get_product_listing \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","page":"<integer>","sort":"<string>"}'
```

### get_related_products_kr

Get styling and pairing recommendations for a Korean H&M product. Returns multiple recommendation lists: 'style_with' (complete-the-look pairings), 'alternatives' (similar items), and 'upsell' (complementary items). Each list contains Korean product names, KRW prices, stock info, images, and Korean URLs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `article_code` | string | Yes | 10-digit article code to get recommendations for (e.g. '1309848011'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/get_related_products_kr \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"article_code":"<string>"}'
```

### get_sale_products

Fetch sale/discounted products for a category. Returns products with both regular and discounted prices, discount percentages, and pagination. Uses the same listing mechanism as category pages but scoped to sale sections.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Sale category path (e.g. 'women/sale/view-all', 'men/sale/view-all'). |
| `page` | integer | No | Page number for pagination (1-based). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/get_sale_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","page":"<integer>"}'
```

### get_similar_items

Fetch similar product recommendations for a given article code. Returns multiple recommendation lists (style_with, alternatives, upsell) each containing related products with pricing and availability.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `article_code` | string | Yes | Article code to find similar items for (e.g. '1347416001'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/get_similar_items \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"article_code":"<string>"}'
```

### get_store_finder

Fetch physical H&M store locations in the US. Optionally filter by city name using case-insensitive substring matching. Returns store details including name, address, coordinates, and opening hours.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | No | Filter stores by city name using substring match (e.g. 'New York', 'Los Angeles'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/get_store_finder \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>"}'
```

### list_products_kr

List Korean H&M products by category path. Returns paginated products with Korean names, KRW prices, member prices, images, and facets. Sort by price is supported. The category path maps to the Korean site's navigation structure. Each page returns up to page_size products (default 36).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Korean site category path (e.g. 'ladies/products/view-all', 'men/new-arrivals/view-all', 'ladies/sale/view-all', 'men/jeans/view-all'). |
| `page` | integer | No | Page number for pagination (1-based). |
| `page_size` | integer | No | Number of products per page. |
| `sort` | string | No | Sort order. Supported values: 'ascPrice' (lowest first), 'descPrice' (highest first). Omit for default. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/list_products_kr \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","page":"<integer>","page_size":"<integer>","sort":"<string>"}'
```

### search_products

Search for products by keyword. Returns matching products with pricing, images, facets, and pagination. Uses H&M's search API for reliable structured results. Each page returns up to 45 products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination (1-based). |
| `query` | string | Yes | Search keyword (e.g. 'jeans', 'denim jacket', 'summer dress'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

### search_products_kr

Search Korean H&M products by keyword. Returns paginated results with Korean product names, KRW prices, member prices (stored separately with eligibility flag), model/product images, sizes, color swatches, and available facets. Sort by price ascending/descending is supported. The API returns informational facets but does not support server-side filtering by color, price range, or sale status. Each page returns up to page_size products (default 36).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination (1-based). |
| `page_size` | integer | No | Number of products per page (max observed: 36). |
| `query` | string | Yes | Search keyword in Korean or English (e.g. 'jeans', '재킷', 'dress'). |
| `sort` | string | No | Sort order. Supported values: 'ascPrice' (lowest first), 'descPrice' (highest first). Omit for relevance. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-h-m-api-0610bb3a/search_products_kr \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","page_size":"<integer>","query":"<string>","sort":"<string>"}'
```