# Shafa — 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 browse second-hand product listings on Ukraine's Shafa.ua marketplace, compare prices, and view detailed seller profiles and reviews. Analyze market trends across product categories and subcategories to make informed purchasing or reselling decisions.

**Category:** Marketplaces | **Website:** [shafa.ua/](https://shafa.ua/) | **Docs:** [parse.bot/marketplace/841f4e8c-c6f4-4938-b010-c361fdba9ece/shafa-ua-api](https://parse.bot/marketplace/841f4e8c-c6f4-4938-b010-c361fdba9ece/shafa-ua-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-shafa-ua-api-841f4e8c/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### browse_listings

Browse product listings with optional category and filter parameters. Supports page-based pagination. Returns items with full product card data including id, url, name, price, brand, seller, sizes, condition, and creation date.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `brands` | string | No | JSON array of brand IDs to filter by (e.g., '[104,183]'). |
| `catalog_slug` | string | No | Category slug to browse (e.g., 'women', 'verhnyaya-odezhda', 'platya'). Omitting returns all listings. |
| `colors` | string | No | JSON array of color IDs to filter by. |
| `conditions` | string | No | JSON array of condition IDs to filter by. |
| `on_sale` | boolean | No | Filter for items currently on sale. |
| `order_by` | string | No | Sort order for results. |
| `page` | integer | No | Page number for pagination. |
| `page_size` | integer | No | Number of results per page. |
| `price_from` | integer | No | Minimum price filter in UAH. |
| `price_to` | integer | No | Maximum price filter in UAH. |
| `sizes` | string | No | JSON array of size IDs to filter by (e.g., '[962,833]'). |
| `ukrainian` | boolean | No | Filter for Ukrainian brands only. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shafa-ua-api-841f4e8c/browse_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brands":"<string>","catalog_slug":"<string>","colors":"<string>","conditions":"<string>","on_sale":"<boolean>","order_by":"<string>","page":"<integer>","page_size":"<integer>","price_from":"<integer>","price_to":"<integer>","sizes":"<string>","ukrainian":"<boolean>"}'
```

### get_categories

Get the full category tree of shafa.ua. Returns the hierarchical catalog structure with all categories and subcategories. Each node contains name, slug, id, and nested subCatalogs arrays. The tree is a single root node with top-level gender/age categories (women, men, kids) each containing deeply nested subcategories.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shafa-ua-api-841f4e8c/get_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_listing_detail

Get full details for a specific listing including product description, images, price, seller info, delivery/payment methods, and similar products. Extracts structured data from the listing page's JSON-LD markup and supplements with GraphQL queries for delivery methods and similar items.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_url` | string | Yes | URL path of the listing (e.g., '/uk/women/verhnyaya-odezhda/shuby/210056181-shuba-norkovaya-_-s-poyasom'). Must contain a numeric product ID in the path. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shafa-ua-api-841f4e8c/get_listing_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_url":"<string>"}'
```

### get_listing_similar

Get similar product recommendations for a specific listing. Extracts the product ID from the listing URL and queries for similar items. May return an empty array if no similar products are available.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_url` | string | Yes | URL path of the listing containing the numeric product ID (e.g., '/uk/women/verhnyaya-odezhda/139633588-slug'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shafa-ua-api-841f4e8c/get_listing_similar \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_url":"<string>"}'
```

### get_seller_listings

Get product listings from a specific seller. Supports cursor-based pagination with endCursor. Returns items with id, url, name, price, brand, and thumbnail.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `after` | string | No | Pagination cursor from endCursor of a previous response. |
| `limit` | integer | No | Maximum number of items to return per page. |
| `username` | string | Yes | Seller username. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shafa-ua-api-841f4e8c/get_seller_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"after":"<string>","limit":"<integer>","username":"<string>"}'
```

### get_seller_profile

Get public profile information for a seller including rating, sold products count, city, activity status, follower count, and product count. Returns input_not_found if the username does not exist.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | string | Yes | Seller username (e.g., 'marfessa', 'annabigun17'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shafa-ua-api-841f4e8c/get_seller_profile \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"<string>"}'
```

### get_seller_reviews

Get reviews for a specific seller. Returns paginated list of buyer reviews with ratings, timestamps, and associated products. Pagination is page-number based.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `username` | string | Yes | Seller username. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shafa-ua-api-841f4e8c/get_seller_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","username":"<string>"}'
```

### get_subcategories

Get subcategories for a specific category slug. Searches the full catalog tree for the given slug and returns its direct children. Returns input_not_found if the slug does not exist in the tree.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `parent_slug` | string | Yes | Category slug to get subcategories for (e.g., 'women', 'kids', 'men', 'verhnyaya-odezhda'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shafa-ua-api-841f4e8c/get_subcategories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parent_slug":"<string>"}'
```

### search_listings

Search for product listings by keyword across all categories. Returns paginated results matching the search query. Uses the same underlying product feed as browse_listings but scoped to a text search.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword (e.g., 'nike', 'zara плаття'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-shafa-ua-api-841f4e8c/search_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```