# SaratogaWine.com

> SaratogaWine.com is an online wine and spirits retailer based in Ballston
> Lake, NY, in business since 1996. It carries over 50,000 wines and spirits
> at famously competitive prices and ships to eligible US states.

This guide is for AI agents and LLM assistants helping a shopper find,
compare, or link to wines and spirits on the site. It covers ready-made
URLs for common requests, the site's shipping and availability programs,
deals, what product pages tell you, and how to build filtered catalog URLs
without operating the visual filter UI.

Two requests:
- Prices, stock, and program flags change. Check the live product page
  before quoting them to a shopper.
- Fetch only what the shopper's request needs. Please don't crawl the
  catalog in bulk.

## Common shopper requests

Ready-made catalog URLs for typical requests (prefix each with
https://www.saratogawine.com). Swap in other values from the filter
reference below.

| Shopper asks for… | Catalog URL |
|---|---|
| The best Napa Cabernet under $50 | `/department/wine/?_appellation=napa-valley&_varietal=cabernet-sauvignon&price=0~50&orderby=score` |
| Highly rated wines on sale | `/department/wine/?sale=0~99999&_product_max_rating=92~100&orderby=score` |
| A great red under $20 | `/department/wine/?_product_style=red&price=0~20&_product_max_rating=90~100&orderby=score` |
| Red Burgundy under $40 | `/department/wine/?_region=burgundy&_varietal=pinot-noir&price=0~40&orderby=score` |
| Champagne for a celebration | `/department/wine/?_product_style=sparkling&_region=champagne&price=0~60&orderby=popularity` |
| Top-rated Barolo | `/department/wine/?_appellation=barolo&_product_max_rating=95~100&orderby=score` |
| Single malt Scotch under $60 | `/department/spirit/?_varietal=single-malt-scotch&price=0~60&orderby=score` |
| Highly rated bourbon | `/department/spirit/?_varietal=bourbon&_product_max_rating=90~100&orderby=score` |
| A gift bottle, $50–150 | `/product-category/gift-wines/?price=50~150&orderby=score` |
| A gift card | `/product/gift-card/` |
| A case of everyday wine with free shipping | `/department/wine/?12-ship-free=yes&price=0~15&orderby=score` |
| White wine that can ship right away | `/department/wine/?rapid-ship=yes&_product_style=white&price=15~30&orderby=popularity` |
| The best deals on buying in quantity | `/product-category/bulk-price-deals/?orderby=popularity` |
| Something to pick up at the store today | `/department/wine/?in-store-today=yes&orderby=popularity` |
| Magnums (1.5L) for a party | `/department/wine/?_size=1500&orderby=score` |
| Everything from one winery or producer | `/department/wine/?_producer=opus-one&orderby=score` |
| A specific wine by name | `/department/wine/?s=opus+one` (or `keyword=opus+one` for title matches only) |
| Other vintages, sizes, or pre-arrival listings of a wine | The links on that wine's product page (see "Product Family") |

Tips:
- `orderby=score` answers "the best"; `orderby=popularity` answers "what
  do people buy". See "Sorting" below.
- `price` filters on the regular price. To find discounted items, add
  `sale=0~99999` (or a narrower sale-price range).
- Too many results? Add a score floor (`_product_max_rating=92~100`) or
  narrow the price range. None? Widen the price range or drop the
  narrowest filter first. See "Reading results" below.
- Don't guess slugs. Look them up (see "Finding valid terms").

## If the shopper needs it by a certain date

- Pre-arrival items arrive months after purchase. See "Pre-arrival" below.
- Items without the Rapid Ship flag need a few extra business days before
  they ship. See "Rapid Ship" below.
- A local shopper who wants something today can shop the store. See "In
  Store Today" below.

## Sending a gift

- Gift pages: `/product-category/gift-wines/` and
  `/product-category/gift-spirits/`. A digital gift card is at
  `/product/gift-card/`.
- An adult 21 or older must sign for the delivery. If no one will be home
  to sign, the sender can choose a FedEx pickup location at checkout.
  FedEx holds the order for a few days so the recipient can pick it up
  when it suits them. **The recipient isn't notified automatically when it
  arrives**, so the sender should tell them where and when to pick it up.
- To check that we ship to the recipient's address, see "Checking whether
  we ship to a location" at the end of this guide.

## Shipping and availability programs

| Param | Meaning | Example |
|---|---|---|
| `12-ship-free` | Qualifies for "12 Ship Free" free shipping (see below) | `?12-ship-free=yes` |
| `rapid-ship` | Stock is already at the shipping facility; ships ASAP with no transfer wait (see below) | `?rapid-ship=yes` |
| `in-store-today` | In stock at our store right now, including in-store-only items (see below) | `?in-store-today=yes` |
| `is-pa` | Pre-arrival: ordered now, arrives from overseas in about 4–8 months (see below) | `?is-pa=yes` |

### 12 Ship Free

Free ground shipping, plus substantially discounted upgraded shipping, on
every full 12-bottle case of qualifying items in an order.

- **Mix and match.** A case doesn't have to be 12 of the same wine. Any 12
  qualifying bottles count, across different products, vintages, and sizes,
  and wine and spirits can be mixed in the same case.
- **Multiples of 12 only.** There's no limit on cases: 24 qualifying bottles
  ship as two free cases. Qualifying bottles beyond the last full 12 (e.g.
  the extra 6 in an order of 18) ship at the normal rate.
- **Other items don't cancel it.** Non-qualifying items can be in the same
  order. They're packed separately and charged at the normal rate; the
  qualifying cases still ship free.
- **Ground is free; faster shipping is heavily discounted.** Express,
  2-day, and other upgraded methods aren't free, but the qualifying cases
  bring their cost down substantially. This matters most when ground
  transit is risky or slow: extreme heat or cold at the destination (e.g.
  Texas or Florida in summer) or long distances (e.g. the West Coast), where
  a faster method protects the wine. Exact rates are shown at checkout.
- **Standard bottle sizes only** (300ml to 1.0L). Only qualifying items carry
  the flag, so if an item has it, its size already qualifies.

How to tell whether an item qualifies:
- Add `12-ship-free=yes` to any catalog URL; only qualifying items are
  listed. E.g.
  `https://www.saratogawine.com/department/wine/?_country=italy&12-ship-free=yes`
- On the site, qualifying items show a "12 FREE" icon on listing pages and a
  banner on the product page.
- The REST product endpoint does **not** expose this flag. Use the catalog URL.

Eligibility is set per product and can change. What counts is the item's
status at the time of purchase, so check shortly before recommending a
final cart.

Full terms: https://www.saratogawine.com/more-info/free-shipping-offers/

### Rapid Ship

Rapid Ship items have stock at the shipping facility, so there's no
transfer wait: they ship as soon as possible. That often means same-day for
orders placed early on a business day, but same-day shipping isn't
guaranteed (e.g. orders placed after hours, on weekends, or on busy days).
Items without the flag are still in stock. They just need about 4–6
business days to transfer to the shipping facility before they ship. When a
shopper needs wine by a specific date, add `rapid-ship=yes` to limit results
to items with no transfer wait.

### In Store Today (visiting the store)

In Store Today items are in stock at our store in Ballston Lake, NY, and
can be bought there right now. Think of it as the Rapid Ship selection plus
in-store-only items. Those are bottles we don't ship, such as some very
large or very small formats and unusually shaped bottles that don't travel
well. They're marked "In-Store Only" on the site.

Use `in-store-today=yes` when a shopper plans to visit the store and wants
to know what they can pick up, or is local and wants something today.
Online orders can also be picked up at the store; choose in-store pickup
at checkout.

Store details for visiting:
https://www.saratogawine.com/more-info/visit-our-store/

### Pre-arrival

Pre-arrival items are not in stock yet. They're ordered from overseas
suppliers and typically arrive 4–8 months after purchase. Don't present them
as available to ship now. If a shopper needs wine soon, point to in-stock
alternatives instead.

Pre-arrival items check out in a separate cart from in-stock items, so a
shopper buying both places two orders.

## Deals

| Deal | What it is | Where to find it |
|---|---|---|
| Bulk Price Deals | A curated selection of our deepest quantity discounts: the per-bottle price at the bulk quantity is well below the single-bottle price. Popular with shoppers. | `/product-category/bulk-price-deals/?orderby=popularity` |
| Sale | Items with a temporary sale price. | Add `sale=0~99999` to any catalog URL, e.g. `/department/wine/?sale=0~99999&orderby=popularity` (or `/department/spirit/`) |
| End Bin | Deep discounts on loose bottles and replaced vintages we're clearing to make room for new stock. Nothing is wrong with the wine; quantities at the End Bin price are limited. | `/product-category/end-bin/?_department=wine&orderby=popularity` (or `spirit`) |
| E-mail offers | Deals from our e-mail offers; the selection rotates regularly. | `/product-category/email-offers/?orderby=popularity` |
| 12 Ship Free | Free shipping on qualifying 12-bottle cases. See "12 Ship Free" above. | Add `12-ship-free=yes` to any catalog URL |

### Bulk pricing: two different things

- **Bulk Price Deals (the category)** are the standout discounts. On listing
  pages each item shows its single-bottle price next to its "Bulk Deal"
  per-bottle price. When a shopper asks for deals or savings from buying in
  quantity, start here.
- **Bulk discounts (on product pages)** appear on many more products, in a
  "Bulk Discounts" block such as "Add 12 bottles at $X each". These are often
  small, sometimes under $1 per bottle, so don't present one as a major deal
  without comparing it to the single-bottle price.
- **The bulk quantity isn't always 12.** It depends on the item's pack size,
  so read the quantity from the product page rather than assuming a case of 12.
- **Bottles beyond the bulk quantity** may be charged the single-bottle
  price, depending on the item. The cart shows the final price once the
  quantity is set.
- **Bulk pricing can combine with 12 Ship Free**, but only on items that
  also carry the 12 Ship Free flag. Not every bulk deal does, so check the
  flag rather than assuming.

## What a product page tells you

Product pages (`/product/{slug}/`) are the richest source for describing a
wine to a shopper. All of the content below is in the page HTML, and no
clicks are needed to reveal it.

- **Ratings & Reviews.** The most useful part of the page for
  recommendations. Each professional review lists the publication, the
  score, and the critic's full tasting note, e.g. "JS 93 pts, James
  Suckling". Use these notes to describe style and flavor, and to match
  wines to what a shopper says they like. Score badges near the top of the
  page show the publication abbreviations (WA, WS, JS, VM, etc.); the Ratings
  & Reviews section spells out the full names.
- **Winery Notes.** Listed with the reviews, but written by the producer,
  not a critic, and carrying no score. Say so if you quote them.
- **Description.** The text under the score badges is usually the top
  score's review, so it's a quick one-paragraph summary of the wine.
- **Details.** Country, region, appellation, sub-appellation, size, color,
  winery, and SKU. The "Shop all from {winery}" link is the `_producer`
  filter for that winery. Background notes on the varietal, country,
  region, and appellation follow.
- **Price.** The per-bottle price. If the item has bulk pricing, a "Bulk
  Discounts" block shows the quantity and per-bottle price (see "Deals").
- **Availability.** A line saying when the item can ship or be picked up,
  e.g. "within 4-6 business days" for items without Rapid Ship.
- **Other vintages, sizes, and pre-arrival.** The "More Purchase Options"
  (same vintage) and "More Vintages" sections, when present. If neither
  appears, no other listing of that wine is available right now. The page's
  structured data also carries the family's `_group` value (see "Same wine,
  other vintages, sizes, and pre-arrival" below).

Notes:
- Reviews belong to the wine and vintage, not the bottle size, so a magnum
  shows the same reviews as the 750ml of the same vintage.
- A different vintage of the same wine has its own reviews. Don't carry
  scores from one vintage over to another.
- Product images are often sample images. Describe the wine from the page
  text, not the label in the photo.
- The catalog `score` sort and `_product_max_rating` filter use the
  wine's highest professional score.

## Adding items to the cart

If you're operating the shopper's own browser, you can add items to the
cart with the product page's "Add to cart" button so the shopper can review
the cart and check out. Leave checkout and payment to the shopper.

- The cart belongs to the browser session it was built in. If you're
  fetching pages on your own, the shopper can't see a cart you build, so
  send them the product links instead.
- Pre-arrival items go in a separate cart from in-stock items (see
  "Pre-arrival").
- Set the quantity before judging price: bulk pricing depends on it (see
  "Bulk pricing").

## Filtering the catalog

### Two ways to filter

1. **Direct URL params** (recommended for agents) — append query params to
   any catalog listing URL (`/department/wine`, `/department/spirit`, `/shop/`,
   or any `/product-category/{slug}/` page). Params combine with `&`.
2. **The on-page filter sidebar** — semantically labeled (`role="group"`,
   accessible names on every control, a live "Showing X of Y results" region)
   if you're driving the page directly rather than constructing URLs.

### Taxonomy filters

| Param | Filters by | Example |
|---|---|---|
| `_department` | `wine` or `spirit` | `?_department=wine` |
| `_product_style` | red / white / rose / sparkling / etc. | `?_product_style=red` |
| `_country` | country of origin | `?_country=france` |
| `_region` | wine region | `?_region=bordeaux` |
| `_appellation` | appellation | `?_appellation=napa-valley` |
| `_varietal` | grape varietal / spirit type | `?_varietal=cabernet-sauvignon` |
| `_vintage` | vintage year | `?_vintage=2019` |
| `_size` | bottle size in ml (`750` = standard bottle, `1500` = magnum) | `?_size=750` |
| `_product_cat` | curated category | `?_product_cat=collectible-wines` |
| `_producer` | winery / producer | `?_producer=opus-one` |

Values are slugs. Comma-separate for OR-matching multiple values:
`?_country=france,italy`.

### Finding valid terms for a taxonomy filter

Don't guess slugs. Each taxonomy above is backed by a real WordPress taxonomy
of the same name (drop the leading underscore) and is readable via the
standard WP REST API:

```
GET https://www.saratogawine.com/wp-json/wp/v2/{taxonomy}
```

Example — valid `_appellation` values:
`https://www.saratogawine.com/wp-json/wp/v2/appellation`

Each item returns `id`, `name`, and `slug` — use `slug` as the filter value
for the URL params above. Ignore any other fields in the response. Results
are paginated (default 10 per page, max `per_page=100`); for a taxonomy with
more than 100 terms, check the `X-WP-Total` / `X-WP-TotalPages` response
headers and page through with `?page=`.

To find one term without paging, add `?search=`. This matters most for
`producer`, which has thousands of terms:
`https://www.saratogawine.com/wp-json/wp/v2/producer?search=opus` returns
Opus One's `id` and `slug` (`opus-one`).

Note: this endpoint does **not** return a product count for the term — use
the product REST endpoint below to get an accurate count instead.

This does not cover `_group` — see "Same wine, other vintages, sizes, and
pre-arrival" below, where the value is only obtainable from a specific
product page — or the
availability/program flags above (`12-ship-free` etc.), which are booleans,
not enumerable taxonomies.

### Range filters

Format is `min~max`.

| Param | Range on | Example |
|---|---|---|
| `price` | regular price | `?price=0~40` |
| `sale` | sale price | `?sale=0~99999` |
| `_product_max_rating` | critic score | `?_product_max_rating=94~100` |

### Search

| Param | Behavior | Example |
|---|---|---|
| `s` | free-text search across title, SKU, and taxonomy names | `?s=cabernet` |
| `keyword` | exact/AND match on product title only | `?keyword=reserve` |

Use `s` for anything that isn't a structured taxonomy above — sub-appellation
names, classifications (Grand Cru, Reserva, etc.), or a specific vineyard or
village name. These often live in the product title or description text
rather than being their own filterable facet, so free-text search will surface
them where a taxonomy param won't.

`s` is for names, not tastes. It matches loosely, so a flavor or style word
returns unrelated products whose names look similar (`?s=jammy` returns
Château Jamais Renoncer). For preferences like "bold and fruity" or "dry
and crisp", filter by style, varietal, and region instead, then read the
reviews on the product pages to pick matches.

### Sorting — `orderby`

| Value | Sorts by |
|---|---|
| *(omitted, no search)* | Default: alphabetical by title; pre-arrival items pushed to the end regardless of title |
| `score` | **Highest critic/rating score first** (not text-search relevance) |
| `price` | Lowest effective price first (sale price if on sale, else regular price) |
| `price-desc` | Highest effective price first |
| `relevance` | Text-search relevance (default automatically when `s` is set) |
| `popularity` | Best-sellers first |

`orderby=score` is the one to reach for when a user wants "the best" wines
in a filtered set rather than "cheapest" or "most popular."

### Same wine, other vintages, sizes, and pre-arrival ("Product Family")

| Param | Meaning |
|---|---|
| `_group` | Every listing SWE currently carries for one specific wine, its Product Family: all vintages, all bottle sizes, and both in-stock and pre-arrival listings |

**`_group` is a unique ID this website uses to link a product family. It
is not an LWIN or any other external wine ID.** You can't compute or guess a
valid value, and values can change, so don't reuse an old one.

To get a value, read it from a product page's structured data (JSON-LD).
It's in the product's `additionalProperty` list as
`{"@type": "PropertyValue", "name": "Group", "value": "<value>"}`. Every
product that belongs to a family has one, even when it's the only listing.
If your tool can't read page scripts, the "More Vintages" links on the page
carry the same value in their URLs.

Then load:
`https://www.saratogawine.com/shop/?_group=<value>`
(add `&_vintage=2019` to narrow to one vintage). Use `/shop/`, not
`/department/wine/`: a spirit's family returns nothing under the wine
department. If that listing shows only
the product you started from, SWE has no other vintage, size, or
pre-arrival listing of that wine right now.

The same vintage and size can show up as two listings, one in stock and one
pre-arrival, each with its own price and availability. Check which one a
shopper wants.

### Reading results: counts, pages, and empty results

- **Count.** Each listing page states the total, e.g. "Showing 1–24 of 910
  results".
- **Pages.** Listings show 24 products per page. For the next page, insert
  `/page/2/` before the query string:
  `https://www.saratogawine.com/department/wine/page/2/?_varietal=cabernet-sauvignon&orderby=score`
  If there are many pages, narrow the filters rather than reading them all.
- **No results.** A listing with nothing to show says "No products were
  found matching your selection." Listings only include products that can
  be ordered now (in stock or pre-arrival), so this means nothing matching
  is available right now, not that SWE never carries it. Widen the filters or suggest close alternatives.

### Combining filters

Params combine freely:
`https://www.saratogawine.com/department/wine/?_country=france&_region=bordeaux&price=20~60&12-ship-free=yes`

## Curated / seasonal listing pages

These pre-built pages are worth knowing directly rather than reconstructing
from filters — several represent editorial selections, not just filter
combinations. Deal pages (Sale, End Bin, E-mail offers, Bulk Price Deals)
are listed under "Deals" above.

| Page | URL |
|---|---|
| Great Wines under $30 | `https://www.saratogawine.com/product-category/great-wines-under-30?orderby=popularity` |
| Collectible wines | `https://www.saratogawine.com/product-category/collectible-wines/` |
| Collectible spirits | `https://www.saratogawine.com/product-category/collectible-spirits/` |
| Gift wines | `https://www.saratogawine.com/product-category/gift-wines/` |
| Gift spirits | `https://www.saratogawine.com/product-category/gift-spirits/` |
| Left Bank Bordeaux | `https://www.saratogawine.com/product-category/left-bank-bordeaux/` |
| Right Bank Bordeaux | `https://www.saratogawine.com/product-category/right-bank-bordeaux/` |
| Lower-alcohol wines | `https://www.saratogawine.com/product-category/lower-alcohol-wines/` |
| Pre-arrival | `https://www.saratogawine.com/product-category/pre-arrival/` |
| Barrel picks | `https://www.saratogawine.com/product-category/barrel-picks/` |
| Wine Spectator Top 100 (current list) | `https://www.saratogawine.com/product-category/spectator-100/` |

Any of the filter/sort params above can be appended to these with `&`.

## Blog and customer service

- **Blog:** https://www.saratogawine.com/blog/ has staff picks, value
  picks, recent tastings, and producer interviews. It's useful
  when a shopper wants suggestions or context rather than a filtered list.
  Posts are dated, so check that any featured wine is still in stock
  before recommending it.
- **Customer service:** https://www.saratogawine.com/more-info/contact-us/
  for anything this guide doesn't answer, such as order status, returns,
  special requests, or questions about a specific bottle.

## Querying products via REST (advanced)

### Querying the product endpoint

For counting or listing matching products yourself rather than just
constructing a catalog URL, query the product collection endpoint:

```
GET https://www.saratogawine.com/wp-json/wp/v2/product?{taxonomy}={term_id}
```

Use the taxonomy name **without** the leading underscore (`country`, not
`_country`), and the term's numeric `id` from the lookup above — **not**
`slug`. Filtering by slug returns a 400 error on this endpoint. Combine
multiple taxonomies with `&`, e.g. `?country=693&varietal=341` (Ukraine +
Vodka).

```
GET https://www.saratogawine.com/wp-json/wp/v2/product?country=693
```

Note: this endpoint returns post/taxonomy data only — no price, stock
quantity, or SKU. Use it for discovery/counting, then follow each result's
`link` to the product page, or use the catalog URL params above to browse
matching products with full storefront data.

### Trim the response with `_fields`

Each product in this endpoint's response includes the full term objects for
every taxonomy attached to it — including each term's long editorial
`description`. A page of 10 products can easily run 60+ KB, almost all of it
repeated term descriptions. Request only the fields you need:

```
GET https://www.saratogawine.com/wp-json/wp/v2/product?varietal=781&_fields=id,title,link
```

For a count alone, request `per_page=1` and read the `X-WP-Total` response
header — you don't need to page through results at all.

### Which to use: REST endpoint or catalog URL?

| Question shape | Use | Why |
|---|---|---|
| "How many X do you carry?" | REST — `X-WP-Total` header | Exact count from a header, no page parsing |
| "Which X are tagged with Y?" / cross-checking taxonomies | REST (with `_fields` including the taxonomy) | Each product exposes its terms; catalog pages don't |
| Anything involving **price** or **sale price** | Catalog URL | REST has no price data |
| "In store today", rapid-ship, 12-ship-free, pre-arrival | Catalog URL | These availability flags exist only as catalog params |
| Sorting (by price, critic score, popularity) | Catalog URL | REST doesn't support these sorts |
| A link to hand to a human shopper | Catalog URL | It's the page they'd actually browse |

If a question mixes both — e.g. "Irish whiskeys under $50 in store today" —
the catalog URL is the only route, because REST can't filter on price or
in-store availability.

Tip: add `department` when the question is about wine only (or spirits
only). Taxonomies like `appellation` aren't limited to wine — e.g.
`appellation=298` (Brunello di Montalcino) also returns grappas made from
Brunello pomace, which the `/department/wine/` catalog page leaves out. Add
`department=174` (Wine) or `department=155` (Spirit) to match what that
catalog page shows:

```
GET https://www.saratogawine.com/wp-json/wp/v2/product?appellation=298&department=174&per_page=1&_fields=id
```

Department ids come from `https://www.saratogawine.com/wp-json/wp/v2/department`.

## Checking whether we ship to a location

If shipping eligibility matters to the shopper, you can look up a ZIP code
at https://www.saratogawine.com/more-info/do-you-ship-to-me/ . This is
optional; use it when you think it would help.

If we don't ship to a shopper's state, FedEx pickup locations are also
offered at checkout. They're often near the borders of states we don't ship
to, so a shopper who lives near a state line may have a convenient pickup
location just across it.