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

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

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/merchbar/`
**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 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.paywithlocus.com/api/wrapped/credits/merchbar/get-artist-id \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.paywithlocus.com/api/wrapped/credits/merchbar/get-artist-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.paywithlocus.com/api/wrapped/credits/merchbar/get-new-arrivals \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.paywithlocus.com/api/wrapped/credits/merchbar/get-on-sale-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.paywithlocus.com/api/wrapped/credits/merchbar/get-product-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.paywithlocus.com/api/wrapped/credits/merchbar/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","limit":"<integer>","on_sale":"<boolean>","page":"<integer>","query":"<string>","sort":"<string>"}'
```

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