# Tottus — 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 across Tottus Peru's supermarket catalog, view detailed product information with filtering and pagination, and discover current promotions and product categories. Find exactly what you're looking for with comprehensive product details and up-to-date promotional offers.

**Category:** E-commerce | **Website:** [tottus.com.pe/](https://tottus.com.pe/) | **Docs:** [parse.bot/marketplace/68de256d-c204-4034-8d31-e0db320657ad/tottus-com-pe-api](https://parse.bot/marketplace/68de256d-c204-4034-8d31-e0db320657ad/tottus-com-pe-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-tottus-com-pe-api-68de256d/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### browse_category

Browse products within a specific category by ID. Returns paginated product listings and available facet filters. Category IDs follow the pattern 'CATGnnnnn' and can be obtained from the get_categories endpoint. 48 products per page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `brand` | string | No | Brand name to filter by, lowercase (e.g., 'tottus', 'paisana') |
| `category_id` | string | Yes | Category ID (e.g., 'CATG16815', 'CATG17605'). Obtain from get_categories endpoint. |
| `category_slug` | string | No | Slug for the category URL path segment (e.g., 'Arroz', 'Aceite') |
| `page` | integer | No | Page number for pagination |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tottus-com-pe-api-68de256d/browse_category \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand":"<string>","category_id":"<string>","category_slug":"<string>","page":"<integer>"}'
```

### get_categories

Retrieve the full category hierarchy from the site navigation. Returns all top-level categories with their second-level and third-level subcategories, each including a category ID and URL. Use the category IDs with browse_category to list products.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tottus-com-pe-api-68de256d/get_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_product_details

Retrieve full product detail by ID and slug. Returns comprehensive information including variants with individual pricing and availability, specifications, breadcrumb category hierarchy, media URLs, and seller info. The slug and product_id are obtained from search_products or browse_category results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Unique product ID (e.g., '145417875'). Obtain from search_products or browse_category results. |
| `slug` | string | Yes | Product URL slug (e.g., 'leche-uht-tottus-entera-tripack-bolsa-800-ml'). Obtain from search_products or browse_category results. |
| `variant_id` | string | No | Specific variant/SKU ID. Defaults to product_id if not provided. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tottus-com-pe-api-68de256d/get_product_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>","slug":"<string>","variant_id":"<string>"}'
```

### get_promotions

Get current promotional banners and CMS containers from the homepage. Returns layout containers with their component configurations and any featured/recommended products. Container data reflects the current homepage layout and promotional campaigns.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tottus-com-pe-api-68de256d/get_promotions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_products

Full-text search over Tottus Peru product catalog. Returns paginated product listings with pricing, availability, and media URLs, plus facet filters (category, price range, brand) for progressive refinement. 48 products per page. Brand and delivery_type filters narrow server-side; finer filtering is client-side over the returned list.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `brand` | string | No | Brand name to filter by, lowercase (e.g., 'tottus', 'xiaomi') |
| `delivery_type` | string | No | Filter by delivery speed: 'express' or 'standard' |
| `page` | integer | No | Page number for pagination |
| `query` | string | Yes | Search keyword (e.g., 'leche', 'arroz', 'smartphone') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tottus-com-pe-api-68de256d/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand":"<string>","delivery_type":"<string>","page":"<integer>","query":"<string>"}'
```