PIM Product API taxonomy

Canonical wine/offer/listing model and the PIM endpoint surface.

Wine2You — PIM Product API Taxonomy

Version: 2.1 · Owner: Wine2You Platform · Status: model update (supersedes v1.0; v2.1 adds §14 Data-exposure controls) Scope: the Product Database — canonical wines, offers (supply), inventory, roles, and how a partner publishes them. Companion documents: Order API Taxonomy and Partner Onboarding.

Design thesis. A wine is an independent fact about the world — a complete, deduplicated register of every wine Wine2You knows it can source, enriched from external databases. It exists with or without any offer. An offer is one Originator's supply listing on that wine (stock + a willingness-to-sell price + selling permissions). A Seller layers its own price on top of the offers it curates. Three things stay separate and never duplicate: the canonical wine (descriptive), the offer (supply/commercial), and the listing (a Seller's shelf price). Inventory is a fourth, fully decoupled concern.

1. Overview & design principles

The three-way split (integrity contract):

wine (canonical, descriptive)  ──1:N──►  offer (originator supply: qty, seller_price, permissions)
                                              │
                                              ├──1:N──►  inventory levels (location × condition)
                                              └──N:1──►  listing (seller shelf price, on its own channel)

Monitored nightly: wines with no offer, offers with no stock, listings referencing missing offers → ops alert.

2. Resource map

3. Identity, external matching & dedup taxonomy

3a. Two-level identity (industry standard)

wine (producer + cuvée)          ──1:N──►  vintage + format = SKU

Vivino (wine.id vs vintage.id), Liv-ex LWIN 7/11/16, CellarTracker (iWine + vintage) all split this way. Wine2You models it as wines (wine, vintage-independent identity) → wine_vintages/variants (vintage + format). One wine row; many vintage/format SKUs.

3b. Tiered match keys (how a wine is matched to external DBs)

3c. External-ID crosswalk (stored per wine, refreshed by re-match)

gtin[], lwin, vivino_wine_id, vivino_vintage_id, wine_searcher_wine_id, cellartracker_iwine, wine_com_product_id, vivc_variety_number[], eambrosia_gi_id, eambrosia_gi_name. This is how a wine sourced from an external DB is linked, not re-keyed.

3d. Dedup rule at ingest

Before creating a wine: resolve Tier 1 → 2 → 3. On match, enrich the existing row (never insert). On no match, create. A POST /v1/wines/match endpoint returns matched | candidate | new with the tier used.

⚠ No "Wine Business Identifier" exists — that is a fabricated SEO artifact. Do not design to it.

4. Canonical wine record (descriptive & compliance)

The canonical wine is independent of offers and holds everything needed to be compliantly described and externally matched.

EU mandatory particulars (1308/2013 Annex VIII + 2019/33 + 2021/2117): category, ABV %, provenance (PDO/PGI), bottler, importer, nominal volume, lot, sulphites, dosage class, ingredients + energy value (label or e-label QR; allergens always physical). 85% rules for vintage / single-variety / sub-region. Wine labelling law = Reg 1308/2013 + Delegated Reg 2019/33 + Reg 1169/2011 + Reg 2021/2117 (not 2019/787 — that is spirit drinks).

5. Offer taxonomy (the Originator's supply listing)

An offer is what an Originator puts forward: "I will sell N units of wine W at seller_price P, to these buyers." Uniqueness: wine_id + originator_id (+ condition for mixed vintages of stock). Zero or many offers per wine.

Sell permissions (default any):

{ "default": "any",
  "allowed_countries": ["CH","DE","NO"],        // if present, only these
  "named_sellers": ["partner_abc"],              // if present, only these
  "blocked_countries": ["US"] }

Evaluated at listing time and re-checked at order capture.

Inventory is separate from offer — the offer carries headline qty_available; per-location truth is the inventory level (§9), so a wine can be sold from several physical pools.

6. Listing taxonomy (a Seller's shelf price)

A Seller curates offers and sets its own selling price on top. The listing is that layer — it never re-states wine or offer data.

Price layering: shelf_price (Seller) is built over seller_price (Originator's offer). The order-side waterfall consumes seller_price as P_B2B; the Seller's margin is its own listing layer (M_Curator-equivalent), not a mutation of the offer.

7. Partner roles (single onboarding, enabled capabilities)

One onboarding flow. Roles are enabled flags, not separate programs.

A partner record holds roles[] = any combination. Example: an Estate = Originator + Fulfiller (+ Seller if it sells direct). A dropship curator = Seller (+ Fulfiller). An importer = Originator (Stock).

8. Two-way endless-isles feed (sync taxonomy)

A partner can be a provider of stock and a receiver/curator of the endless-isles feed — both directions, independently enabled.

• Curation: a receiving partner selects which wines/offers to surface (feed-curation module), sets its own shelf price, and can block by country/seller — it does not blindly mirror.
• Indirect sourcing: feed-curation also enables "other inventories" — wines offered by a partner but not yet in any offer can be proposed, then promoted to an offer by an Originator (§ fulfillment).
• Idempotent upserts keyed on external_id / wine_id+originator_id; at-least-once with Idempotency-Key.

9. Inventory taxonomy (decoupled from the wine)

Ownership: each originator's stock sits at its own stock_location with owner_entity_id. Availability is scoped by the sales channel's linked locations (Medusa v2 reality — see §11), which is what enables cross-seller dropship: Seller B sells Estate A's stock with no warehouse.

⚠ is_network_shareable is not a Medusa v2 concept (verified: no such field). The real mechanisms are product ↔ sales_channel (M:N), sales_channel ↔ stock_location (M:N), and variant ↔ inventory_item (M:N). Wine2You models "shareable across the network" as its own flag on the offer (network_shareable), resolved against channel↔location links — do not cite a Medusa field that does not exist.

10. Location & tax/duty taxonomy

Location (LocationDataSchema): location_id, gln (GS1), location_type (WINERY_ESTATE|BONDED_WAREHOUSE|DUTY_PAID_WAREHOUSE|RETAIL_STORE|3PL_FULFILLMENT_CENTER|CONSIGNMENT_CELLAR|IN_TRANSIT_CONTAINER), address, geo_coordinates, tax_jurisdiction {country, state, excise_tax_zone_id, eu_seed_number}, capabilities {supports_d2c_fulfillment, supports_b2b_wholesale, supports_bonded_transfer, temperature_controlled}.

Tax/duty (TaxDutiesContextSchema): hs_tariff_code, country_of_origin, duty_status (DUTY_PAID|IN_BOND|DUTY_FREE|EXCISE_SUSPENDED|PRE_ARRIVAL), volumetric_metrics {volume_liters, net_weight_kg, gross_weight_kg, abv_percentage, liters_pure_alcohol}, tax_classification {sales_tax_category_code, vat_rate_type, excise_tax_category}, cross_border_terms {incoterm, import_duty_rate_percent, preferential_trade_agreement_code}, packaging_and_environmental_levies {container_deposit_fee, epr_recycling_category_code}.

LPA = volume_liters × abv_percentage / 100 — the excise base in every destination.

11. Medusa alignment (v2)

12. Fulfilment logic (estate-first, then other inventories)

At order capture, routing resolves stock by priority:

1. Estate direct — if the wine's estate is an Originator on W2Y, prefer estate stock (estate sale).
2. Other inventories — otherwise (or if estate ATP is short), route to other enabled offers/stock. Indirect sourcing is gated by feed-curation: an originator's permissions (allowed countries / named sellers / default any) and network_shareable must permit the selling partner + destination.
3. Split — if no single source covers the quantity, split across sources (each becomes its own fulfilment leg from its own stock location).

Selection inputs: atp, seller_price, incoterm/freight, permissions, destination eligibility, and priority tier (estate > indirect). The chosen offer's seller_price becomes that line's P_B2B in the waterfall.

13. Webhooks & events taxonomy (proposed)

Delivery: at-least-once, signed, idempotency key = event id.

14. Data-exposure controls (anti-scrape)

Normative detail (C1–C4, enforcement points, OpenAPI requirements): Wine2You-Data-Exposure-Controls-Spec.md.

Problem. An entity-scoped key + a rate limit does not stop a legitimate partner from page-walking GET /v1/wines, GET /v1/offers or GET /v1/inventory/network-snapshot until it holds the whole wine and offer tables. These controls make partial data the only data a key can ever hold.

13a. Read-path scoping (the primary defence — enforced on every read): Every list/detail read is filtered, server-side, before serialization. A row is returned only if all pass:

• network_shareable == true on the offer (offers not flagged shareable are invisible to any partner that is not the owning entity — see §9).
• The caller's entity passes the offer's permissions (allowed_countries[] / named_sellers[], default any) — the same gate the fulfilment logic uses (§12).
• The caller's sales-channel / tenant scope admits the row (channel↔location links, §9).

Entity-scoped keys (Unkey + OpenFGA) decide which entity you are; this filter decides what that entity may see. Both are required — neither substitutes for the other.

13b. Pagination is bounded, not infinite:

• Every list endpoint is cursor-paginated with a hard page_size cap (default 50, max 200).
• A network_snapshot-class read (the whole-network view, §2) requires the explicit read:network scope, which ordinary partner keys do not receive.

13c. Per-key row quota (kills page-walking):

• Each key carries a records-returned quota per rolling period (e.g. 50k rows/day) in addition to the per-key request rate limit. When exceeded → 429 with Retry-After, and the counter is per-entity so one partner cannot exhaust another's budget.

13d. Audit & anomaly signal:

• Every read records key_id, entity_id, endpoint, rows_returned, cursor_span. Sudden volume spikes (a key pulling N× its trailing average) raise an ops alert rather than silently serving the data.

15. Worked example — canonical wine with two offers and one listing

{
  "title": "Barolo DOCG — Cantina X",
  "slug": "barolo-docg-cantina-x",
  "producer": "prod_cantina_x",
  "cuvee": "Barolo DOCG",
  "medusa_product_id": "prod_01HX…",
  "vintage": 2019, "is_non_vintage": false,
  "colour": "red", "category": "wine",
  "abv": 14.5, "volume_in_liters": 0.75,
  "hs_code": "2204.21.79",
  "terroir": {
    "country": "IT", "region": "Piemonte", "sub_region": "Langhe",
    "appellation": "Barolo DOCG", "designation": "DOCG", "quality_scheme": "PDO",
    "grape_varieties": [{ "variety": "Nebbiolo", "vivc_number": 8885, "percentage": 100 }]
  },
  "eu_compliance": {
    "bottler": { "name": "Cantina X S.r.l.", "address": "…" },
    "lot_number": "L2019-0043", "allergens": ["sulphites"],
    "ingredients": "Grapes: Nebbiolo.", "energy_kj_per_100ml": 310, "energy_kcal_per_100ml": 74,
    "e_label_url": "https://…/e-label/L2019-0043"
  },
  "external_ids": [
    { "source": "gtin", "external_id": "8001234567890", "confidence": 1.0 },
    { "source": "lwin", "external_id": "1005767", "confidence": 0.98 },
    { "source": "vivino_wine_id", "external_id": "1105374", "confidence": 0.91 },
    { "source": "eambrosia_gi_id", "external_id": "PDO-IT-B0442", "confidence": 1.0 }
  ],
  "ratings": [{ "source": "vivino", "score": 4.3, "scale": 5 }],
  "status": "published",
  "offers": [
    { "offer_id": "off_estate_1", "originator_id": "partner_estate_x", "seller_price": 18.00,
      "currency": "EUR", "qty_available": 240, "incoterm": "FCA",
      "permissions": { "default": "any" }, "network_shareable": true, "status": "active" },
    { "offer_id": "off_importer_1", "originator_id": "partner_importer_ch", "seller_price": 20.50,
      "currency": "EUR", "qty_available": 60, "incoterm": "DAP",
      "permissions": { "allowed_countries": ["CH","NO"] }, "status": "active" }
  ],
  "listings": [
    { "listing_id": "lst_curator_9", "seller_id": "partner_curator_ch",
      "offer_id": "off_estate_1", "channel_id": "ch_shop_ch", "shelf_price": 34.90,
      "currency": "CHF", "status": "live" }
  ]
}

One canonical wine, two originator offers at different seller_price, one seller's shelf price on top — no duplication of the wine record.

16. Best-practice notes

• Dedup before create: tiered matching (§3) at ingest; never insert a wine that matches an existing key.
• Idempotency: every write takes Idempotency-Key; bulk feed retries are safe.
• Partial updates: PATCH merges; commercial values (offer/listing price, stock) update independently of the descriptive version train — a price change never re-publishes the wine description.
• Three-way integrity: nightly monitor wines ↔ offers ↔ listings ↔ inventory; orphans flagged.
• Why the canonical wine must be independent: the same wine record serves every storefront, feed, match and customs document — authored once, consumed everywhere. Duplicating it per supplier is where catalogue projects bleed cost and where "the same wine twice" breaks matching.
• Roles over programs: one onboarding, enable capabilities — avoids four parallel integration guides.
• Scoping beats rate-limiting: an entity-scoped key with a generous rate limit can still walk every page. The read-path filter (network_shareable + permissions + channel/tenant scope), a bounded cursor page size and a per-key row quota are what actually keep wine and offer from being bulk-extracted (§14).