# Cigars International — 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 cigars by brand, category, and daily deals while reading customer reviews to find the perfect smoke. Discover store locations and explore comprehensive product information across Cigars International's entire catalog.

**Category:** E-commerce | **Website:** [cigarsinternational.com/](https://cigarsinternational.com/) | **Docs:** [parse.bot/marketplace/665423a7-2225-4c92-92ba-ae536c166b0d/cigarsinternational-com-api](https://parse.bot/marketplace/665423a7-2225-4c92-92ba-ae536c166b0d/cigarsinternational-com-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-cigarsinternational-com-api-665423a7/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### browse_category

Browse cigars by category slug. Returns paginated products (30 per page) in that category. Category slugs come from brand URLs in list_brands (path after /category/) or site navigation paths like 'cigars'.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_slug` | string | Yes | Category path slug (e.g. 'cigars', 'big-list-of-brands/macanudo-cigars'). Derived from brand page URLs returned by list_brands. |
| `page` | integer | No | Page number for pagination. Each page returns up to 30 results. |

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

### get_customer_reviews

Retrieve customer reviews for a specific product SKU via the Yotpo reviews API. Returns paginated reviews with scores, content, and reviewer info. The product_id is a SKU ID from get_product_page results (skus[*].sku_id).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for review pagination. |
| `page_size` | integer | No | Number of reviews per page. |
| `product_id` | string | Yes | Product SKU ID (e.g. 'AIA-PM-1080'). Found in get_product_page results as skus[*].sku_id. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cigarsinternational-com-api-665423a7/get_customer_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","page_size":"<integer>","product_id":"<string>"}'
```

### get_daily_deal

Retrieve the current Joe Cigar daily deal products. Returns deal products with pricing tiers, ratings, and availability. Deals rotate daily.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cigarsinternational-com-api-665423a7/get_daily_deal \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_product_page

Retrieve full details for a cigar product page by its product ID. Returns product name, description, rating, characteristics map, and individual SKU variants with pricing and availability. The product_id comes from search_products results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Product ID from search results or brand pages (e.g. 'AIA-PM', 'MA7-PM'). Found in search_products results as product_id. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cigarsinternational-com-api-665423a7/get_product_page \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>"}'
```

### get_store_locations

Retrieve all physical CI Superstore locations with addresses, phone numbers, and geographic coordinates. No input required.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cigarsinternational-com-api-665423a7/get_store_locations \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### list_brands

Retrieve the alphabetical list of all cigar brands from the brand directory page. Optionally filter by starting letter. Returns brand names and their category page URLs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `letter` | string | No | Filter brands by starting letter (e.g. 'A', 'M'). Case-insensitive. Omitting returns all brands. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cigarsinternational-com-api-665423a7/list_brands \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"letter":"<string>"}'
```

### search_products

Full-text search across all products. Returns paginated results (30 per page) with basic product info. Pagination via page number; total count reflects server-side matches.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. Each page returns up to 30 results. |
| `query` | string | Yes | Search keyword (e.g. 'acid', 'cohiba', 'macanudo'). |

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