# Cigars International — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/cigars-international/`
**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

### 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.beta.paywithlocus.com/api/wrapped/credits/cigars-international/browse-category \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/cigars-international/get-customer-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/cigars-international/get-daily-deal \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/cigars-international/get-product-page \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/cigars-international/get-store-locations \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/cigars-international/list-brands \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/cigars-international/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.