# Shop — 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.

> Browse and search products across Shop.app, view detailed product information, explore merchants and their offerings, discover categories, and find featured items from the homepage. Get autocomplete suggestions to quickly find what you're looking for.

**Category:** E-commerce | **Website:** [shop.app/](https://shop.app/) | **Docs:** [parse.bot/marketplace/dfeb47f1-d0a9-4e3b-b25e-8f8b3ebea71a/shop-app-api](https://parse.bot/marketplace/dfeb47f1-d0a9-4e3b-b25e-8f8b3ebea71a/shop-app-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-shop-app-api-dfeb47f1/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_homepage_featured_products

Retrieves featured products from the shop.app homepage hero carousel. Returns up to 10 products across categories (general, beauty, fashion). No parameters needed. Each product includes basic info suitable for drilling into details via get_product_details.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shop-app-api-dfeb47f1/get_homepage_featured_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_merchant_info

Retrieves merchant profile information including name, website, reviews, contacts, store sections, and visual theme. Returns the full shop object with all available metadata. Use the handle from get_search_autocomplete or get_product_details results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | Yes | Merchant handle/slug from get_search_autocomplete or get_product_details results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shop-app-api-dfeb47f1/get_merchant_info \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handle":"<string>"}'
```

### get_merchant_products

Retrieves paginated product listings for a specific merchant, sorted by most sales. Returns product nodes with pricing, images, and review analytics, plus flat pagination fields (hasNextPage, endCursor). Use broker_id from get_merchant_info or get_search_autocomplete results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `after` | string | No | Pagination cursor from previous response's endCursor field. |
| `broker_id` | string | Yes | Merchant numeric ID from get_merchant_info or get_search_autocomplete results. |
| `first` | integer | No | Number of products to retrieve per page (1-100). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shop-app-api-dfeb47f1/get_merchant_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"after":"<string>","broker_id":"<string>","first":"<integer>"}'
```

### get_product_details

Retrieves full details for a single product including current price, original price (if discounted), images, rating, review count, and merchant info. Requires both product_id and product_slug which are available from get_homepage_featured_products or get_merchant_products results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Numeric product ID from get_homepage_featured_products or get_merchant_products results. |
| `product_slug` | string | Yes | Product URL slug from get_homepage_featured_products or get_merchant_products results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shop-app-api-dfeb47f1/get_product_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>","product_slug":"<string>"}'
```

### get_search_autocomplete

Fetches search autocomplete suggestions for a query prefix. Returns both query suggestions (text completions) and matching shop suggestions (with id, name, handle, rating). Useful for discovering merchant handles and IDs for other endpoints.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query prefix to get suggestions for. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shop-app-api-dfeb47f1/get_search_autocomplete \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### list_categories

Returns all top-level shopping categories available on shop.app. Categories include a Shopify GID, display name, and whether they have subcategories. No parameters needed.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shop-app-api-dfeb47f1/list_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_merchants_by_category

Searches for merchants within a shop.app category page. Returns merchants with their rating and review analytics. Each category page yields approximately 25-35 merchants extracted from the category's product feed. Accepts a category slug (mapped to the site's category ID internally) and optional filters for review count and rating ranges. Results are paginated within the extracted set; use page and page_size to navigate. The category data comes from one upstream page load per call.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Category slug to search within. Known categories: women, men, beauty, home, fitness-nutrition, baby-toddler, food-drinks, sporting-goods, toys-games, pet-supplies, accessories, electronics, arts-crafts, luggage-bags. Aliases like clothing, fashion, womenswear, menswear, fitness, baby, food, sports, toys, pet, arts, luggage are also accepted. |
| `max_rating` | number | No | Maximum average rating. Merchants above this rating are excluded. |
| `max_reviews` | integer | No | Maximum number of product reviews the merchant may have. Merchants with more reviews are excluded. |
| `min_rating` | number | No | Minimum average rating (e.g. 4.5). Merchants below this rating are excluded. |
| `min_reviews` | integer | No | Minimum number of product reviews the merchant must have. Merchants with fewer reviews are excluded. |
| `page` | integer | No | Page number for pagination (1-indexed). |
| `page_size` | integer | No | Number of merchants per page. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shop-app-api-dfeb47f1/search_merchants_by_category \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","max_rating":"<number>","max_reviews":"<integer>","min_rating":"<number>","min_reviews":"<integer>","page":"<integer>","page_size":"<integer>"}'
```