# Flipp — 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 grocery deals and weekly advertisements across multiple retailers by keyword, store location, or zip code to find the best prices on items you need. Browse flyer items and current promotions to plan your shopping and save money on groceries.

**Category:** Food & Dining | **Website:** [flipp.com/](https://flipp.com/) | **Docs:** [parse.bot/marketplace/3e4c2e53-c818-4645-bc08-46bc714c464e/flipp-com-api](https://parse.bot/marketplace/3e4c2e53-c818-4645-bc08-46bc714c464e/flipp-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-flipp-com-api-3e4c2e53/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_flyer_items

Retrieve all sale items from a specific weekly ad flyer. Use a flyer_id obtained from get_weekly_ads to browse a retailer's full circular contents, including item names, prices, brands, and validity dates.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `flyer_id` | string | Yes | Flyer identifier from get_weekly_ads results (e.g. 8032529). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-flipp-com-api-3e4c2e53/get_flyer_items \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"flyer_id":"<string>"}'
```

### get_weekly_ads

List current weekly ad flyers available near a postal code. Optionally filter by retailer name to find a specific store's circular. Each result includes the flyer ID needed to retrieve individual items via get_flyer_items.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `merchant_name` | string | No | Case-insensitive retailer name filter (e.g. Safeway, Walmart). Partial matches are supported. Omitting returns all available flyers. |
| `postal_code` | string | Yes | 5-digit US ZIP code to find weekly ads near. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-flipp-com-api-3e4c2e53/get_weekly_ads \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"merchant_name":"<string>","postal_code":"<string>"}'
```

### search_deals

Full-text search for grocery deals and sale items from weekly circulars. Returns flyer items matching the query from all retailers near the given postal code, including item name, current and original price, merchant, and validity dates.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `postal_code` | string | Yes | 5-digit US ZIP code to search deals near. |
| `query` | string | Yes | Search keyword for deals (e.g. chicken, milk, cereal). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-flipp-com-api-3e4c2e53/search_deals \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"postal_code":"<string>","query":"<string>"}'
```