# Total Wine API

> Total Wine store navigation menu and categories (unverified)

- Vendor: `totalwineapi` · version 1.0 · category E-commerce · tags total wine api, totalwine api, wine store api, liquor store api, beer wine spirits api, alcohol retail api
- Datasource: custom HTTP routes
- Marketplace page: https://apiclay.com/api/totalwineapi
- This document: https://apiclay.com/docs/totalwineapi.md
- OpenAPI 3.1: https://apiclay.com/api/totalwineapi/openapi.json
- MCP: connect https://api.apiclay.com/v1/mcp (see https://apiclay.com/llms.txt), then `apiclay_describe_api` with vendor `totalwineapi`
- Updated: 2026-11-18

## About

## Total Wine API

Total Wine &amp; More's store navigation menu (departments and their subcategories) from the Total Wine app API.

Data comes from **totalwine.com** (https://www.totalwine.com). Every route below calls the site's own endpoint directly and returns the upstream response unchanged.

Typical flow: `/menus` -&gt; `/categories`

### Routes

#### GET `/menus` - Menus (navigation)
The store's navigation menu.

| Param | In | Type | Required | Description |
|---|---|---|---|---|
| storeId | query | string | yes | Total Wine store id. |
| shoppingMethod | query | string | yes | `INSTORE_PICKUP` or `DELIVERY`. |
| x-totalwine-ts | header | string | no | Current Unix time in seconds (the app sends it). |

Returns (fields the source code reads; not yet verified live):
- `navigation.content[]`: departments with `name` and `url`, and their child entries

#### GET `/categories` - Categories (navigation subcategories)
The same navigation menu; the subcategories are the children of a department.

| Param | In | Type | Required | Description |
|---|---|---|---|---|
| storeId | query | string | yes | Total Wine store id. |
| shoppingMethod | query | string | yes | `INSTORE_PICKUP` or `DELIVERY`. |
| x-totalwine-ts | header | string | no | Current Unix time in seconds. |

Returns (fields the source code reads; not yet verified live):
- `navigation.content[]...`: subcategory entries with `name` and `url`

### Not yet available

| Endpoint | Why |
|---|---|
| products | each request needs a fresh signature header computed from the path and time |
| product | each request needs a fresh signature header computed from the path and time |

### Caveats

- These routes were written from MealMe's source code and have not been tested live yet (the site blocks plain requests from the test machine).
- The source site uses bot protection (PerimeterX); calls may be blocked until that is handled.
- Upstream calls change over time (embedded keys, field names). Verify responses before relying on them.
- Not affiliated with totalwine.com or Total Wine &amp; More.

## Pricing

- Pay as you go: 0.0012 credits/request
- Trial: 1 free requests per buyer
- Billing order: trial requests -> subscribed plan requests -> pay as you go. 1 credit's USD value is shown on the marketplace page.

## HTTP routes

Only the public, buyer-facing parts of each route are listed; vendor-side credentials stay on the gateway.

### GET /menus — Menus (navigation)
- Gateway: `GET https://api.apiclay.com/v1/api/totalwineapi/menus`
- Public headers: `x-totalwine-ts`
- Public query params: `storeId` (string, required), `shoppingMethod` (string, required)
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### GET /categories — Categories (navigation subcategories)
- Gateway: `GET https://api.apiclay.com/v1/api/totalwineapi/categories`
- Public headers: `x-totalwine-ts`
- Public query params: `storeId` (string, required), `shoppingMethod` (string, required)
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

## Call example

```bash
curl -X GET "https://api.apiclay.com/v1/api/totalwineapi/menus?storeId=<storeId>&shoppingMethod=<shoppingMethod>" \
  -H "token: <YOUR_APICLAY_TOKEN>"
```

Index of every published API: https://apiclay.com/llms.txt
