# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/shop/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/shop/get-homepage-featured-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/shop/get-merchant-info \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/shop/get-merchant-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/shop/get-product-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/shop/get-search-autocomplete \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/shop/list-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/shop/search-merchants-by-category \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.