# Merchbar — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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.

> Search and discover music merchandise across vinyls, CDs, apparel, and accessories, then track product details, new arrivals, and sales by artist. Find exactly what you're looking for with real-time product information and pricing updates.

**Category:** Music | **Website:** [merchbar.com/](https://merchbar.com/) | **Docs:** [parse.bot/marketplace/fec9187c-feb0-446a-afa1-5c89712a4490/merchbar-com-api](https://parse.bot/marketplace/fec9187c-feb0-446a-afa1-5c89712a4490/merchbar-com-api)

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

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/parse-merchbar-com-api-fec9187c/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### Get artist id

Look up an artist's brand ID by name. Returns the brand ID and canonical name of the top matching artist. The brand ID can then be passed to get_artist_products, get_new_arrivals, or get_on_sale_products to scope results to that artist.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Artist name to search for (e.g., Metallica, The Beatles). |

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

### Get artist products

Retrieve merchandise listings for a specific artist by brand ID or name query. At least one of artist_id or artist_query must be provided. Supports category filtering, sale filtering, sorting, and pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_id` | string | No | Numeric brand ID of the artist. Obtainable from the get_artist_id endpoint. |
| `artist_query` | string | No | Artist name to search by if the brand ID is not known. |
| `category` | string | No | Category filter (e.g., Vinyl, CD, Shirts). |
| `limit` | integer | No | Number of results per page. |
| `on_sale` | boolean | No | Filter for products currently on sale. |
| `page` | integer | No | Page number for pagination. |
| `sort` | string | No | Sort order for results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-merchbar-com-api-fec9187c/get_artist_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"artist_id":"<string>","artist_query":"<string>","category":"<string>","limit":"<integer>","on_sale":"<boolean>","page":"<integer>","sort":"<string>"}'
```

### Get new arrivals

Retrieve newest product listings sorted by creation date descending. Optionally filtered by search keyword or artist brand ID. Same result shape as search_products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_id` | string | No | Artist brand ID to filter new arrivals for a specific artist. |
| `limit` | integer | No | Number of results per page. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | No | Search keyword to filter new arrivals. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-merchbar-com-api-fec9187c/get_new_arrivals \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"artist_id":"<string>","limit":"<integer>","page":"<integer>","query":"<string>"}'
```

### Get on sale products

Retrieve products currently on sale, sorted by discount percentage descending. Optionally filtered by search keyword or artist brand ID. Same result shape as search_products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_id` | string | No | Artist brand ID to filter sale products for a specific artist. |
| `limit` | integer | No | Number of results per page. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | No | Search keyword to filter sale products. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-merchbar-com-api-fec9187c/get_on_sale_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"artist_id":"<string>","limit":"<integer>","page":"<integer>","query":"<string>"}'
```

### Get product details

Fetch full details for a single product page including HTML description, all image sizes, variant options, and pricing breakdown. Requires a product URL or path slug obtainable from search results. Each call is a page fetch (heavier than search); batch via search first, then drill into individual products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_url` | string | Yes | Full product page URL or path slug (e.g., /rock-alternative/artist/product-name-123). URLs can be obtained from search_products or get_artist_products results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-merchbar-com-api-fec9187c/get_product_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_url":"<string>"}'
```

### Search products

Full-text search across the Merchbar catalog. Matches product names, brands, tags, and UPC codes. Supports category filtering, sale filtering, and multiple sort orders. Paginates via page number; each page returns up to `limit` items.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category to filter by (e.g., Vinyl, CD, Shirts). |
| `limit` | integer | No | Number of results per page. |
| `on_sale` | boolean | No | Filter for products currently on sale. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | No | Search keyword. Use '*' to match all products. |
| `sort` | string | No | Sort order for results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-merchbar-com-api-fec9187c/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","limit":"<integer>","on_sale":"<boolean>","page":"<integer>","query":"<string>","sort":"<string>"}'
```