# Mercari Japan — 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 browse millions of product listings on Mercari Japan with bilingual support, filtering by categories and getting detailed pricing, item specifications, and seller information. Access comprehensive marketplace data including product summaries, category overviews, and individual seller profiles to find exactly what you're looking for.

**Category:** Marketplaces | **Website:** [jp.mercari.com/](https://jp.mercari.com/) | **Docs:** [parse.bot/marketplace/48cf336c-1769-42fe-a6e5-84751511e765/jp-mercari-com-api](https://parse.bot/marketplace/48cf336c-1769-42fe-a6e5-84751511e765/jp-mercari-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/mercari-japan/`
**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 all categories

Fetch the complete hierarchical category tree for Mercari Japan. Returns all product categories with parent-child relationships, display ordering, image URLs, and short labels. Use category IDs from this tree to filter search results or browse items by category.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mercari-japan/get-all-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get category items

Browse items under a specific category with optional price and sort filters. Uses the same search engine as search_items but requires a category_id. Returns up to 120 items per page with cursor-based pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Category ID to browse (from get_all_categories) |
| `order` | string | No | Sort order |
| `page_token` | string | No | Pagination token from previous response's next_page_token. Managed automatically by the SDK paginator. |
| `price_max` | integer | No | Maximum price in JPY |
| `price_min` | integer | No | Minimum price in JPY |
| `sort` | string | No | Sort field. Omitting sorts by relevance. |
| `status` | string | No | Item status filter |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mercari-japan/get-category-items \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","order":"<string>","page_token":"<string>","price_max":"<integer>","price_min":"<integer>","sort":"<string>","status":"<string>"}'
```

### Get item detail

Fetch full details for a single Mercari item by its ID. Returns the complete listing including description, seller information, images, condition, shipping details, and category. Item IDs start with 'm' followed by digits (e.g. 'm77009256155'). Returns stale_input if the item does not exist.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_id` | string | Yes | Mercari item ID starting with 'm' followed by digits (e.g. 'm77009256155') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mercari-japan/get-item-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"item_id":"<string>"}'
```

### Get search summary

Get aggregate price statistics for a search query based on up to 120 sample items. Returns min, max, average, and median prices across all statuses. Useful for market analysis before purchasing. The sample_size indicates how many items were used for the calculation (max 120 even when total_count is higher).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `keyword` | string | Yes | Search keyword to get price statistics for |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mercari-japan/get-search-summary \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"<string>"}'
```

### Get seller profile

Fetch all items listed by a specific seller. Returns items across all statuses (on sale, sold out, trading) from the seller's profile. Seller IDs are numeric and can be found in get_item_detail responses.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | Yes | Seller's numeric user ID (from get_item_detail seller.id field) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mercari-japan/get-seller-profile \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"<string>"}'
```

### Search items

Search for items on Mercari Japan with optional filters including keyword, category, price range, and sort options. Returns up to 120 items per page with cursor-based pagination via next_page_token. When no keyword or category is specified, returns trending/recent items. Total count is capped at 15000 by the upstream API.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | Filter by category ID from get_all_categories endpoint |
| `keyword` | string | No | Search keyword to match item titles and descriptions |
| `order` | string | No | Sort order |
| `page_token` | string | No | Pagination token from previous response's next_page_token. Managed automatically by the SDK paginator. |
| `price_max` | integer | No | Maximum price in JPY |
| `price_min` | integer | No | Minimum price in JPY |
| `sort` | string | No | Sort field. Omitting sorts by relevance. |
| `status` | string | No | Item status filter |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mercari-japan/search-items \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","keyword":"<string>","order":"<string>","page_token":"<string>","price_max":"<integer>","price_min":"<integer>","sort":"<string>","status":"<string>"}'
```

## Next steps

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