Info API Essentials

Retrend’s /v2/info/* endpoints power product detail pages, search, merchandising rails, and kiosk views. This guide groups the most-used endpoints by responsibility, shows required params, and explains how to fan out follow-up calls (most search-style endpoints return IDs; you hydrate them with detail endpoints).

These examples assume you already created a session token as described in API Dependencies and you will authenticate each request with organization-id and x-session headers. Include kiosk headers (kiosk-id, x-kiosk, x-temp-kiosk, x-device-id) if you are calling from a kiosk client.

How this guide is organized

• Entity detail: /store, /kiosk, /organization, /product, /recipe, /substitute
• Discovery & merchandising: /featured-products, /featured-recipes, /search-products, /search-recipes, /broadtypes, /subtypes, /brands, /store-distances
• Conversations: /conversations

Quick reference

Entity detail

Store

GET /v2/info/store?store_id=STORE_UUID

Returns identifiers, address, phone, geo (latitude, longitude), active flags, and store number. Use to show availability context or to seed distance calculations.

Kiosk

GET /v2/info/kiosk?kiosk_id=KIOSK_ID

Returns kiosk metadata: organization, store binding, kiosk number, name, status, and heartbeat timestamps. Include kiosk headers when calling from the device.

Organization

GET /v2/info/organization?organization_id=ORG_UUID

Returns organization profile (name, contact links, billing fields) plus default_store_id to fall back when a client has not selected a store.

Product detail

GET /v2/info/product?product_id=PID&store_id=STORE_UUID

Returns a product object with:

• Identity: pid, external_id, display_name, brand, description, broad_type, sub_type, alcohol_by_volume, flags (is_preferred, is_featured, is_substitute, is_alcoholic).
• Variants: array of variants with sku, is_primary, size, rewards_points, list_price, sale_price, location, qty_in_stock, image_url, public_id.

Example:

curl -X GET "https://api.retrend.ai/v2/info/product?product_id=PID&store_id=STORE_UUID" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION"

Recipe detail

GET /v2/info/recipe?recipe_id=RID&store_id=STORE_UUID&target_price=25

Returns a recipe with rid, name, instructions, serves, optional image_url, and ingredients (each includes name, quantity, unit, garnish/serveware flags, and optional pid when mapped to a product).

Substitute products

GET /v2/info/substitute?pid=PID&store_id=STORE_UUID

Returns budget, competitive, and premium product candidates (each a full ProductSummary or null when unavailable).

Discovery & merchandising

Featured rails

• GET /v2/info/featured-products?limit=8&shuffle=true
• GET /v2/info/featured-recipes?limit=6&shuffle=false

Both return arrays of IDs. Fetch product or recipe details separately to render cards.

Product search

POST /v2/info/search-products supports faceting and semantic filters via query params, plus an optional JSON body to ignore IDs (array of UUIDs or null).

Common query params: description, name, brand, vintage, country_code, region_code, broadtype, subtype, target_price, num_results (defaults to API setting), store_id, use_ai_filter, add_suggested, only_in_stock.

Example:

curl -X POST "https://api.retrend.ai/v2/info/search-products?description=berry%20notes&broadtype=Wine&subtype=Red&num_results=12&store_id=STORE_UUID&only_in_stock=true" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION" \
  -H "Content-Type: application/json" \
  -d "[\"PID_TO_SKIP\"]"

Response: products array of product IDs. Hydrate with /v2/info/product.

Recipe search

POST /v2/info/search-recipes accepts query params (description, name, serveware, serves, num_results) and an optional JSON body specifying ingredients or garnishes lists.

Example:

curl -X POST "https://api.retrend.ai/v2/info/search-recipes?description=smoky&serves=1&num_results=8" \
  -H "organization-id: $RETREND_ORG_ID" \
  -H "x-session: $RETREND_SESSION" \
  -H "Content-Type: application/json" \
  -d "{\"ingredients\": [\"Rye\", \"Orange Bitters\"], \"garnishes\": [\"Orange Peel\"]}"

Response: recipes array of recipe IDs. Hydrate with /v2/info/recipe.

Taxonomy lists

• GET /v2/info/broadtypes?store_id=STORE_UUID&in_stock_only=true → array of broad types (id, name, description, is_featured, image_url).
• GET /v2/info/subtypes?broadtype_name=Wine&store_id=STORE_UUID&in_stock_only=true → array of subtypes (id, name, description, broadtype_id).

Brands

GET /v2/info/brands?q=her&is_featured=true&limit=10

Returns brands with id, name, image_url, is_featured. Use for autocomplete and brand landing pages.

Store distances

GET /v2/info/store-distances?store_id=STORE_UUID&max_miles=50

Returns distances: list of { "store_id": "...", "distance": <number> }. Use for nearest-store selectors or pickup routing.

Conversations

POST /v2/info/conversations

Request body:

{
  "start_date": "2024-01-01T00:00:00Z",
  "end_date": "2024-01-31T23:59:59Z",
  "num_results": 20,
  "include_blank": false
}

Response: conversations array with cid, client_id, store_num, store_id, start_time, end_time, short_summary, intent, is_kiosk. Use to populate history views, then fetch summaries separately once available.

Implementation tips

• Hydration: Search and featured endpoints return IDs; follow with /info/product or /info/recipe to render full cards.
• Store sensitivity: Pass store_id when present so pricing and availability reflect the shopper’s location. Use store-distances to pick a fallback.
• Kiosk headers: Include kiosk identifiers for kiosk clients to ensure policies and logging apply correctly.
• Pagination-lite: limit and num_results cap returns; use client-side “load more” by reissuing calls with different criteria.