Help center

Basics through Pro features

API

Public Wine List

Retrieve published wine lists as JSON from your website or app. No login, API key, access token, or Authorization header is required. This API is read-only.

Base URL:https://api.v2.winecode.app

Start with your public URL

If your public URL is https://winecode.app/example-shop, use example-shop as the API groupKey. Both the public URL alias and the original group key are accepted. Unpublished groups cannot be retrieved.

curl 'https://api.v2.winecode.app/group/example-shop'

example-shop is a placeholder. Replace it with the value from your public URL and encode path parameters with encodeURIComponent or an equivalent function.

View wine list publication settings

Endpoints

Public wine list

GET https://api.v2.winecode.app/group/:groupKey

An array of eligible public wines, sorted by display price in ascending order. Returns an empty array [] when no wines match.

Wine details

GET https://api.v2.winecode.app/group/:groupKey/:threadId

One wine. Returns HTTP 200 with an empty body for wines outside the group, drafts, hidden wines, or wines without a display price. Nonexistent IDs return 403. Wines with zero stock may be returned.

Tags

GET https://api.v2.winecode.app/group/tags/:groupKey

An array with tagId, label, typeId, isSecret, useQty, and hasThread.

Shop information and display settings

GET https://api.v2.winecode.app/group/description/:groupKey

Returns shop contact information, a description, priceType, wine type display names, and other settings.

threadId is an integer from the list response. There are no pagination, search, or sorting query parameters. Filter the returned array in your application.

Eligibility for lists and details

The list excludes drafts and returns wines belonging to the group with positive stock (qty), a positive public display price (price.sell), and no individual hide setting. Results are sorted by display price in ascending order.

Details do not filter by stock, so wines with zero stock may be returned. Wines outside the group, drafts, hidden wines, and wines without a display price return HTTP 200 with an empty body. Nonexistent or deleted threadId values return 403. Check the HTTP status and whether the body is empty before parsing JSON.
const groupKey = encodeURIComponent('example-shop');
const response = await fetch(`https://api.v2.winecode.app/group/${groupKey}/12345`);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const body = await response.text();
const wine = body === '' ? null : JSON.parse(body);

Wine fields

These are representative fields. Responses also contain other fields. The example is an excerpt using fictional data.

[
  {
    "threadId": 12345,
    "type": "RED",
    "name": "サンプル・ピノ・ノワール",
    "label": "Sample Pinot Noir",
    "year": 2022,
    "area": "フランス ブルゴーニュ",
    "producer": "サンプル生産者",
    "variety": "ピノ・ノワール",
    "tastingNote": "赤い果実の香り。",
    "qty": 3,
    "price": {
      "sell": 8800,
      "suggest": 11000,
      "glass": 1500
    },
    "currencyCode": {
      "sell": "JPY",
      "suggest": "JPY",
      "glass": "JPY"
    },
    "enableSecondPrice": false,
    "images": [],
    "attachments": []
  }
]
FieldDescription
threadIdWine (thread) ID
typeRED / WHITE / SPARKLING / CHAMPAGNE / ROSE / ORANGE / OTHER
name / labelWine name and foreign-language label. Includes group-specific name overrides.
yearVintage year. 0 means non-vintage.
area / producer / appellation / varietyRegion, producer, appellation, and grape variety
tastingNote / tastingTagsTasting notes and tasting tags. Notes include group-specific overrides.
qtyStock quantity within the group
priceAmounts for sell / suggest / glass. Unset values may be null.
currencyCodeCurrency codes retain their original price-type keys. For the display price, use sell when priceType is 0, glass when 1, and suggest when 2.
enableSecondPriceWhether to display a second price
attachments / imagesPublic image metadata and URLs. Hidden images are excluded.

The public wine response excludes price.purchase, memo, groupId, purchaseDate, place, and history. Hidden images are also excluded.

Display prices and shop information

Shop information includes groupId, groupKey, groupAlias, type, shopName, shopAddress, shopPhone, shopUrl, shopInstagram, shopReservationUrl, description, priceType, threadTypeSettings, and threadTypes. Contact fields and the description may be null.

priceType is 0 for the selling price, 1 for the glass price, and 2 for the suggested retail price. price.sell contains the selected display price. currencyCode keys retain their original price types.

When enableSecondPrice is true and priceType is not 0, price.glass contains the original selling price for use as a second price. threadTypeSettings is DEFAULT or CUSTOM. threadTypes maps wine types to display names, with null for unset names.

Tags

Tags include tagId, label, typeId, isSecret, useQty, and hasThread. An unset typeId becomes 0; hasThread may be null. useQty counts threads using the tag and may differ from the public wine list count. Exclude tags with isSecret set to true from public interfaces.

Errors and caching

  • 403: Unknown or unpublished groupKey, or nonexistent or deleted threadId.
  • 400: threadId is not an integer.
  • 503: Temporarily unavailable, for example during maintenance.

This is an example 403 response for an unknown or unpublished groupKey. A nonexistent threadId returns a different error message.

{"statusCode":403,"message":"正常なリクエストではありません"}

Lists and nonempty wine detail responses return Cache-Control: public, max-age=60, s-maxage=60. Caching may delay changes to stock, prices, and publication settings. Tags, shop information, and empty details do not receive this 60-second cache setting.

Browser requests also work without authentication headers. Reuse cached responses when polling and avoid unnecessarily frequent requests.