# Albertsons — 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.

> Browse Albertsons' current weekly ad deals and pricing by location, search for specific products with autocomplete suggestions, and discover all discounted items available in any weekly ad publication. Save time finding the best grocery deals and product availability at your local Albertsons store.

**Category:** Food & Dining | **Website:** [www.albertsons.com/](https://www.albertsons.com/) | **Docs:** [parse.bot/marketplace/ea191b4f-33ac-4b17-88ec-82ba7f20172e/albertsons-com-api](https://parse.bot/marketplace/ea191b4f-33ac-4b17-88ec-82ba7f20172e/albertsons-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/albertsons/`
**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 weekly ad products

Get all products/deals from a specific weekly ad publication. Returns product names, brands, sale prices, deal descriptions (BOGO, multi-buy), categories, and validity dates. If no publication_id is provided, automatically fetches the main weekly ad for the given location.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Filter products by category name (case-insensitive partial match). Verified categories include: Fruits & Vegetables, Meat & Seafood, Beverages, Bread & Bakery, Dairy, Eggs & Cheese, Cookies, Snacks & Candy, Frozen Foods, Canned Goods & Soups, Paper, Cleaning & Home, Wine, Beer & Spirits, Deli, Flowers & Decor. |
| `postal_code` | string | No | US postal/zip code (used only if publication_id is not provided). |
| `publication_id` | string | No | Weekly ad publication ID (from get_weekly_ads endpoint's ads[*].id field). If omitted, uses the first/main weekly ad for the location. |
| `store_code` | string | No | Albertsons store ID (used only if publication_id is not provided). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/albertsons/get-weekly-ad-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","postal_code":"<string>","publication_id":"<string>","store_code":"<string>"}'
```

### Get weekly ads

Get list of current weekly ad publications (flyers) for a given store location. Returns all active weekly ads including the main Weekly Ad, Bonus Online Savings, Big Book of Savings, etc. The store_code takes precedence over postal_code when both are provided.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `postal_code` | string | No | US postal/zip code for the store location. Used alongside store_code; when store_code is set, postal_code does not independently change results. |
| `store_code` | string | No | Albertsons store ID number. Takes precedence over postal_code for determining which ads to return. Invalid store codes result in an upstream 422 error. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/albertsons/get-weekly-ads \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"postal_code":"<string>","store_code":"<string>"}'
```

### Search suggestions

Get product search autocomplete suggestions for a query. Returns up to 20 suggestions. The first suggestion typically includes department and brand filter metadata; remaining suggestions contain only query text.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query text (e.g., 'milk', 'chicken', 'bread'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/albertsons/search-suggestions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

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