# Flipp — 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 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

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

### 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.beta.paywithlocus.com/api/wrapped/credits/flipp/get-flyer-items \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/flipp/get-weekly-ads \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/flipp/search-deals \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"postal_code":"<string>","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.