# Coupons — 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 discover coupons, printable offers, and store-specific deals from Coupons.com. Browse top featured offers, find deals across thousands of retailers, and access aggregated coupon data including discount amounts, usage conditions, and expiration details.

**Category:** E-commerce | **Website:** [coupons.com/](https://coupons.com/) | **Docs:** [parse.bot/marketplace/cffeaf1e-b13f-42de-9478-4188b90d83ae/coupons-com-api](https://parse.bot/marketplace/cffeaf1e-b13f-42de-9478-4188b90d83ae/coupons-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-coupons-com-api-cffeaf1e/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_all_stores

Retrieve the full directory of stores available on coupons.com, organized alphabetically. Returns over 2000 stores with their display names and URL slugs. The slug can be passed to get_store_coupons to fetch coupons for a specific retailer.

**Estimated cost:** Metered

_No parameters required._

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

### get_coupons

Get digital grocery and product coupons. Each item in the offers array wraps coupon data under an 'offer' key containing brand, dollar value (in cents), UPC codes, expiration dates, and redemption instructions. Image URLs can be constructed by concatenating image_url_prefix with each offer's image_url_suffix.

**Estimated cost:** Metered

_No parameters required._

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

### get_printable_coupons

Get printable grocery coupons. Same structure as get_coupons but filtered to printable offers. Each item wraps coupon data under an 'offer' key with brand, value, UPCs, expiration dates, and print authorization status.

**Estimated cost:** Metered

_No parameters required._

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

### get_recent_coupons

Get recent coupon codes and deals from a coupons.com category page sorted by expiration date (soonest first). Returns coupons from the specified category with retailer information and slugs usable in get_store_coupons. The category page provides offer titles, types, end times, and retailer mappings; coupon codes and verification status are not available at the category level and return null.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category slug from the coupons.com all-categories path (e.g. 'fashion-and-accessories', 'food-and-grocery', 'electronics'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-coupons-com-api-cffeaf1e/get_recent_coupons \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>"}'
```

### get_store_coupons

Get all available coupon codes and deals for a specific retailer by slug. Returns flat coupon objects with codes, descriptions, expiration times, and verification status. The store slug can be obtained from get_all_stores or search_stores endpoints.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Store slug from the store URL path (e.g. 'amazon', 'nike', 'walmart'). Obtainable from get_all_stores or search_stores results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-coupons-com-api-cffeaf1e/get_store_coupons \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### get_stores_summary

Retrieve all stores from the coupons.com directory with their active voucher count. Returns every store from the alphabetical directory enriched with the number of currently active coupons/vouchers (sourced from the site's popular stores data). Stores without a known active count report 0. The slug field is directly usable as input to get_store_coupons. Useful for diffing voucher counts across polling runs to selectively decide which stores warrant a full get_store_coupons call.

**Estimated cost:** Metered

_No parameters required._

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

### get_top_coupons

Get today's featured top coupons and deals curated from various stores. Returns high-value offers with retailer info, promo codes, expiration details, terms, and images. Typically returns 15-25 top offers.

**Estimated cost:** Metered

_No parameters required._

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

### search_stores

Search for retailers by name. Returns matching stores with metadata including active voucher count, logo path, and landing page URL. Each result contains a nested retailer object and a retailerLandingPage with the store's URL slug.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search term for store name (e.g. 'nike', 'walmart', 'amazon') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-coupons-com-api-cffeaf1e/search_stores \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```