Wine2You-Partner-Onboarding

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.

Step	What happens	Applies to
1 · Apply	Create partner record: legal entity, country, contact, payout details.	all
2 · Verify	KYC / payout identity verification (by the payment provider, not stored by W2Y).	all
3 · Enable roles	Grant `Originator` / `Fulfiller` / `Seller` (any combination).	per partner
4 · Configure	Permissions (per Originator), channel + shelf pricing (per Seller), fulfilment (per Fulfiller).	per role
5 · Integrate	Credentials, feed endpoints (push/pull), first wine/offer/listing.	per role
6 · Go live	Publish gate; first order.	all

2. Role matrix

Role	Enables	Key configuration	Typical partner
Originator	Adds data to the canonical wines DB and/or inventory to the offer table.	Sub-type (`Estate` \| `Collector` \| `Stock`/importer); sell permissions (allowed countries / named sellers / default `any`); `network_shareable`.	Estate, collector, importer
Fulfiller	Picks, packs, ships. On by default for Originators; can also feed wines not yet in any offer.	Stock locations, capabilities (d2c, bonded transfer, temp-controlled), carrier setup.	Estate warehouse, 3PL, importer
Seller	Generates its own sales orders. Sells own stock (if also Originator) and/or others' inventory it curates. Sets its own shelf price over the offer-feed.	Sales channel, curated shop (markup, layout), which offers to surface.	Webshop, curator shop, dropship reseller

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)

Direction	Endpoint	Who	Purpose
Pull (platform → you)	`POST /v1/sync/pull` / webhook	Seller / Fulfiller	receive wines + offers + price/stock deltas to curate
Push (you → platform)	`POST /v1/sync/push`	Originator	contribute wines + offers (upsert, idempotent)
Status	`GET /v1/sync/status`	all	`last_cursor`, pending, errors

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)

Estate direct — if the estate is on W2Y, its stock is preferred.
Other inventories — otherwise route to other enabled offers whose permissions allow the destination/buyer (indirect sourcing, gated by feed-curation).
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)
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.