Partner onboarding reference

The single onboarding flow and the full credentials checklist.

Wine2You — Partner Onboarding

Version: 1.0 · Owner: Wine2You Platform · Status: single onboarding flow (merges Supplier + Retailer onboarding) Scope: one front door for every partner. Roles (Originator · Fulfiller · Seller) are enabled capabilities, not separate programs. Companion documents: PIM Product API Taxonomy, Order API Taxonomy.

Naming. We merge what would otherwise be "Supplier onboarding" and "Retailer onboarding" into one Partner Onboarding with a role matrix. A partner signs up once and enables the roles it needs. This keeps the model deduplicated — one flow, one partner record, many roles — exactly as the canonical wine keeps one row per wine regardless of how many suppliers offer it.

1. One flow, many roles

Onboarding is a single sequence. Roles are toggles on the partner record, granted after the shared steps.

2. Role matrix

Examples of role combinations:

• Estate = Originator + Fulfiller (+ Seller if it also sells direct). Provides wine data + stock; ships its own; preferred in routing.
• Importer / distributor = Originator (Stock) (+ Fulfiller). Provides stock offers; may be an indirect source.
• Collector = Originator (Collector) (+ Fulfiller). Contributes rare wines + stock.
• Curator webshop = Seller (+ Fulfiller if it ships). Curates offers from others, sets shelf price, sells.
• Dropship reseller = Seller. Generates orders fulfilled by other sellers'/originators' inventory.

One partner can hold any combination — an Estate that also runs a shop is Originator + Fulfiller + Seller on one record.

3. What each role connects to

Originator

• Wine data → canonical wines. POST /v1/wines (or bulk POST /v1/sync/push). Ingest dedups by tiered match keys (GTIN → LWIN → normalized natural key) — your wine lands in the shared register, not a private copy.
• Stock → offers. POST /v1/offers with seller_price (your willing-to-sell, pre tax/duty/platform/fee/ shipping), qty, incoterm, valid_from/to.
• Permissions. Set who may buy: allowed_countries, named_sellers, or default any. Re-checked at listing and at order capture.
• Feed (inbound). Push updates; Idempotency-Key makes retries safe.

Fulfiller

• Locations & capabilities. Register stock locations (gln, type, geo, tax jurisdiction, capabilities).
• Fulfilment. Receive Fulfiller instruction, pick/pack/ship, emit tracking per leg.
• Feed unoffered wines. Optionally contribute wines not yet in any offer (proposed, promoted later).

Seller

• Curate. Receive the endless-isles feed (POST /v1/sync/pull), select what to surface, block by country/seller — you do not mirror blindly.
• Shelf price. POST /v1/listings — your own price over the offer's seller_price.
• Channel. One sales channel + curated shop (markup, layout); publishable API key scopes your storefront.
• Orders. POST /v1/orders through the single order surface; routing applies estate-first, then other inventories you're permitted to use.

4. Two-way feed (Endless Isles ↔ partner)

A partner may be both a provider and a receiver simultaneously (e.g. an Estate pushes its stock and pulls the broader feed to curate for its own shop).

5. Fulfilment model (estate-first, then other inventories)

1. Estate direct — if the estate is on W2Y, its stock is preferred.
2. Other inventories — otherwise route to other enabled offers whose permissions allow the destination/buyer (indirect sourcing, gated by feed-curation).
3. Split — short quantities split across sources; each becomes its own fulfilment leg from its own location.

You fulfil the legs whose stock you hold (unless you've delegated fulfilment to a 3PL/Fulfiller partner).

6. Credentials & integration checklist

• Partner record created + payout identity verified
• Roles enabled (Originator / Fulfiller / Seller)
• API credentials issued (publishable key for storefront; secret key for partner-scoped admin access) — keys are entity-scoped; read access is bounded by the data-exposure controls (C1–C4, see Wine2You-Data-Exposure-Controls-Spec.md): a key sees only rows it is scoped to and cannot bulk-extract the wine/offer tables.
• Webhooks subscribed (wine.*, offer.*, listing.*, stock.changed, sync.completed, order.*)
• First wine pushed (dedup matched) / first offer created / first listing created (per role)
• Permissions set (Originator) · channel + shelf price live (Seller) · location + carrier ready (Fulfiller)
• Test order end-to-end → published

7. Reference: canonical vs offer vs listing (the model in one picture)

        CANONICAL WINE  (independent, deduplicated, externally matched)
        ──────────────────────────────────────────────────────────────
        title · producer · cuvée · vintage · colour · category · ABV ·
        region tree · grapes (VIVC) · EU-compliance block · GTIN/LWIN/crosswalk
                         │
        ┌────────────────┴─────────────────┐
        ▼                                  ▼
   OFFER (Originator supply)          OFFER (another Originator)
   seller_price · qty · permissions    seller_price · qty · permissions
        │                                  │
        ▼                                  ▼
   LISTING (Seller shelf price)        LISTING (same or other Seller)
   = seller_price + Seller's margin    over whichever offer it curates

One wine, many offers, many listings — no duplication anywhere.

8. Why merge, not separate

• One front door. Partners often wear two hats (an Estate that also sells). Separate Supplier/Retailer guides would force them through two flows and two records.
• Roles over programs. The capability is a flag, not a category — the API is identical, only enabled endpoints differ.
• Deduplicated like the data. Just as the canonical wine is one row no matter how many suppliers, the partner is one record no matter how many roles.
• Simpler to maintain. One document, one onboarding sequence, one role matrix to keep current.