# Bidorbuy — 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 products on Bob Shop, view detailed product information, seller profiles and ratings, explore category listings, and discover current promotions. Get search suggestions and navigate the complete product catalog to find exactly what you're looking for.

**Category:** Marketplaces | **Website:** [bidorbuy.co.za/](https://bidorbuy.co.za/) | **Docs:** [parse.bot/marketplace/9070bd47-0711-4b54-980b-0b8242015335/bidorbuy-co-za-api](https://parse.bot/marketplace/9070bd47-0711-4b54-980b-0b8242015335/bidorbuy-co-za-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-bidorbuy-co-za-api-9070bd47/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_category_listings

Browse products within a specific category. Returns paginated product listings identical in shape to search_products. Use get_category_tree to discover available category IDs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | The category ID. Use get_category_tree to discover available IDs. |
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bidorbuy-co-za-api-9070bd47/get_category_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","page":"<integer>"}'
```

### get_category_tree

Retrieve the flat list of top-level categories available on Bob Shop. Returns category IDs and names for use with search_products category_id filter and get_category_listings.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bidorbuy-co-za-api-9070bd47/get_category_tree \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_homepage_promotions

Get current promotional listings from the homepage (Weekend Specials). Returns an array of promoted product listings. Promotions rotate periodically.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bidorbuy-co-za-api-9070bd47/get_homepage_promotions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_product_details

Retrieve full details for a single product by its numeric ID. Returns price, title, seller name, images, full category path, and product attributes (typically delivery estimates). The product ID can be obtained from search_products or get_category_listings results (tradeId field).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | The unique product ID (numeric string). Obtain from search_products results tradeId field. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bidorbuy-co-za-api-9070bd47/get_product_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>"}'
```

### get_seller_profile

Get a seller's active listings. Returns paginated product listings for the specified seller. The seller_id can be obtained from any product listing's seller.userId field.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for listings. |
| `seller_id` | string | Yes | The seller's numeric ID. Obtain from search_products results seller.userId field. |
| `seller_name` | string | No | The seller's display name for the URL slug. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bidorbuy-co-za-api-9070bd47/get_seller_profile \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","seller_id":"<string>","seller_name":"<string>"}'
```

### get_seller_ratings

Get ratings and reviews for a seller, including individual review comments and a summary of positive/neutral/negative counts by time period (Past month, Past 3 months, Total till date).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `seller_id` | string | Yes | The seller's numeric ID. Obtain from search_products results seller.userId field. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bidorbuy-co-za-api-9070bd47/get_seller_ratings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seller_id":"<string>"}'
```

### search_products

Full-text search across Bob Shop listings. query matches product titles; results are paginated and sortable. Supports filtering by category, condition, price range, and sale type. Each result includes full product card data: pricing, seller info, images, and category hierarchy.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | Category ID to filter by. Use -1 for all categories. Discover IDs via get_category_tree. |
| `condition` | string | No | Item condition filter. |
| `max_price` | string | No | Maximum price filter in ZAR. |
| `min_price` | string | No | Minimum price filter in ZAR. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | Yes | Search keywords. |
| `sale_type` | string | No | Listing type filter. |
| `sort` | string | No | Sort order for results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bidorbuy-co-za-api-9070bd47/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","condition":"<string>","max_price":"<string>","min_price":"<string>","page":"<integer>","query":"<string>","sale_type":"<string>","sort":"<string>"}'
```

### search_suggestions

Get real-time search suggestions for a partial query. Returns suggested search terms with optional category context and trade counts. Useful for autocomplete or discovering popular search terms.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Partial search term to get suggestions for. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-bidorbuy-co-za-api-9070bd47/search_suggestions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```