# Checkers — 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 for groceries, browse product categories, and find Checkers store locations across South Africa all in one place. Get detailed product information, discover popular items, and locate the nearest store to shop conveniently.

**Category:** Food & Dining | **Website:** [checkers.co.za/](https://checkers.co.za/) | **Docs:** [parse.bot/marketplace/aba8c6dd-64c9-4cda-bb5b-f294ac126540/checkers-co-za-api](https://parse.bot/marketplace/aba8c6dd-64c9-4cda-bb5b-f294ac126540/checkers-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/checkers/`
**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

### Find stores

Find Checkers stores near a geographic coordinate. Returns an array of stores sorted by proximity, each with name, brand (CHECKERS, CHECKERS_HYPER, CHECKERS_LIQUORSHOP, MEDIRITE), full address, geolocation, trading hours, facilities, and departments. Child stores (e.g. LiquorShop inside a Hyper) are nested in the parent's 'children' array.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lat` | number | Yes | Latitude of the location (e.g. -33.89 for Cape Town area) |
| `lng` | number | Yes | Longitude of the location (e.g. 18.56 for Cape Town area) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/checkers/find-stores \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"lat":"<number>","lng":"<number>"}'
```

### Get category products

List all products within a specific category or sub-category. Accepts a category ID from list_categories and returns paginated product results with the same shape as search_products. Use totalCount for pagination bounds.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Category ID from the list_categories endpoint (e.g. '67075e5eff987811364007e6' for Appliances) |
| `limit` | integer | No | Number of results per page |
| `page` | integer | No | Page number (0-indexed) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/checkers/get-category-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","limit":"<integer>","page":"<integer>"}'
```

### Get image url

Resolve a Checkers image ID to its full CDN URL. Accepts an imageId as returned by product endpoints (imageIds, imageId fields) and category endpoints (imageId field), and returns the complete URL where the image is served. No network request is made to the image host; this is a pure URL construction.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `image_id` | string | Yes | Image identifier as returned by product and category endpoints (e.g. '6a5973a6f76689d8c79e254f') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/checkers/get-image-url \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"image_id":"<string>"}'
```

### Get popular searches

Retrieve the most popular search terms on the Checkers site, ranked by cumulative search count. Each term includes its count and an updatedOn timestamp. Useful for discovering trending products or auto-suggesting search queries.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/checkers/get-popular-searches \
  -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 URL slug. The slug format is the product name lowercased with spaces replaced by hyphens, followed by the article number and 'EA' (e.g. 'clover-fresh-full-cream-milk-2l-10136729EA'). Returns nutritional info, ingredients, allergens, images, stock, and pricing.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Product URL slug in format '<product-name-hyphenated>-<articleNumber>EA' (e.g. 'clover-fresh-full-cream-milk-2l-10136729EA') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/checkers/get-product-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### List categories

Retrieve the full product department and category hierarchy as a tree structure. Returns all categories up to 3 levels deep (departments → categories → sub-categories). Each node includes its ID, name, level, and nested children. Use category IDs from this tree as input to get_category_products.

**Estimated cost:** Metered

_No parameters required._

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

### Search products

Full-text search over all Checkers products by keyword. Returns a paginated list of products with prices (in ZAR cents), stock availability, images, promotions, and nutritional attributes. Results include a totalCount field for pagination. Each product exposes a slug-compatible identifier (lowercase name + articleNumber + 'EA') usable with get_product_details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of results per page |
| `page` | integer | No | Page number (0-indexed) |
| `query` | string | Yes | Search keyword (e.g. 'milk', 'bread', 'chips') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/checkers/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","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.