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

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/bidorbuy/`
**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 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/credits/bidorbuy/get-category-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/bidorbuy/get-category-tree \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/bidorbuy/get-homepage-promotions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/bidorbuy/get-product-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/bidorbuy/get-seller-profile \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/bidorbuy/get-seller-ratings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/bidorbuy/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/bidorbuy/search-suggestions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<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.