Skip to main content
Product families let an application present related source SKUs together while preserving the facts that belong to each SKU. A family is a reviewed relationship, not a shared inventory record. The examples use NEKTIR_API_BASE for the API origin supplied with pilot access. api.nektir.com currently hosts documentation, not the production API service.

​
Wine: browse vintages and choose an available bottle

​
1. Search once per family

Use collapse=family with a text search. A grouped result has a non-null search_group; an ungrouped product keeps search_group: null.
The representative product makes collapsed search fast and compact. Its price and availability belong only to that SKU. Use the returned family ID before rendering choices.

​
2. Load every current vintage

Each member includes vintage_year, package_size, price, status, inventory_retrieved_at, and availability_summary. Sort or label options from these structured values instead of reparsing the display name.
Prices and status values can change. Example values illustrate the response shape and should not be treated as current without making the request.

​
3. Show nearby availability for the selected SKU

After the customer chooses a vintage and package, use that member’s product ID:
Do not interpret an empty page as no stock unless meta.coverage.status and unchecked_pair_count establish complete coverage for the requested policy.

​
Whiskey: compare age statements, then package variants

​
1. Find reviewed whiskey families

Browse families directly when the interface starts from a brand or product line:
Or collapse product search:

​
2. Compare ages without parsing names

The Macallan Double Cask family exposes 15 Year, 18 Year, and 30 Year as member-level age_statement values. Price, lifecycle status, package size, and availability remain member-specific.
If an age also has multiple package variants, keep both members visible or filter products with family_id and relationship_type=package_variant:

​
3. Open a product without another family request

Both product lookup routes include family_members, so a product page can render its current vintage, age, and package alternatives immediately:
The detail response also contains compact meta.freshness.catalog and meta.freshness.inventory clocks. retrieved_at is Nektir’s retrieval time; source_updated_at remains null when DABS does not provide one.

​
Show observed family changes

Family detail includes an observed_history summary across its current members: retained event counts, observed price range, last price and inventory change times, members currently reporting stock, and retention boundaries. Load the underlying SKU-specific events when an interface needs a timeline:
The API computes this view from retained product events at the pinned publication revision; it does not create a second family-history record. A family can gain reviewed members later, so persist event IDs for deduplication and keep each event’s product SKU visible. Inventory differences remain observations—not purchases, sales, or guaranteed restocks.

​
Lifecycle and availability rules

  • A family does not make a discontinued or unavailable member active.
  • Never sum member inventory unless the application explicitly wants availability across substitutable products.
  • reported_positive_store_count reports observations, not consumer purchase eligibility.
  • Prefer stable family and product UUIDs. Preserve all six characters of DABS SKUs, including leading zeroes.
  • Treat null vintage, age, price, or retrieval time as unknown—not zero, non-vintage, free, or recently checked.