Draft • Partner Integration

Data Schema (Draft)

This page describes what FYND stores for partner website integrations and what we may request from partners. It’s designed to support: (1) reliable try-on UX, (2) measurable attribution/ROI, (3) future model improvements, and (4) billing & pricing strategies.

Principle
Minimize PII
Prefer anonymous session IDs and event data. Store images only with explicit retention rules.
Principle
Join everything
Every event should carry client_id, session_id, and (when relevant) job_id, product_id.
Principle
Retention by default
Uploads/outputs can auto-delete unless the user opts in for improvement.

1) partners

Partner/client account configuration.

partners
- client_id (pk)
- client_name
- status (active|paused)
- domains[] (prod + staging)
- allowed_origins[]
- auth_mode (api_key|hmac|jwt)
- api_key_hash (if api_key)
- daily_limit
- features { tryon_enabled, embed_enabled, categories_enabled[] }
- retention_policy { uploads_days, outputs_days, analytics_days }
- created_at, updated_at

2) catalog_products

A lightweight mirror of partner catalog for joining analytics to items.

catalog_products
- id (pk)
- client_id (fk partners.client_id)
- product_id (partner)
- variant_id (partner)
- sku (optional)
- title
- category (TOP|BOTTOM|OUTERWEAR|DRESS|ACCESSORY)
- color
- size
- price_amount
- price_currency
- image_urls[]
- availability (in_stock|oos|unknown)
- last_seen_at
- created_at, updated_at

3) sessions

Anonymous user sessions. Avoid direct identifiers where possible.

sessions
- session_id (pk, uuid)
- client_id (fk)
- created_at
- last_seen_at
- locale
- language
- device_type (mobile|desktop)
- user_agent (optional)
- country (optional)
- consent { analytics:boolean, improvement:boolean, version:string }
- utm { source, medium, campaign, content, term } (optional)

4) tryon_jobs

One record per generation attempt (core for debugging, cost, and improvements).

tryon_jobs
- job_id (pk, uuid)
- client_id (fk)
- session_id (fk)
- created_at
- status (started|succeeded|failed)
- error_code (nullable)
- engine (v1|v2|v3)
- engine_version (git sha or semantic version)
- product_id, variant_id (nullable if user upload only)
- input_mode (user_photo|preset_avatar|model_image)
- input_image_ref (nullable, sensitive)
- garment_image_refs[] (urls or internal refs)
- output_image_ref (nullable, sensitive)
- timings_ms { upload, generation, total }
- cost_estimate { provider, units, usd } (optional)
- created_utc (string optional, for display)

5) events

Unified event stream for product analytics and attribution.

events
- event_id (pk, uuid)
- client_id (fk)
- session_id (fk)
- job_id (nullable fk tryon_jobs.job_id)
- created_at
- name (impression|click_tryon|upload_started|upload_success|upload_failed|
       generate_started|generate_success|generate_failed|result_viewed|
       add_to_cart|checkout_started|purchase_completed|refund)
- page_type (pdp|plp|cart|other)
- placement_id (string)
- product_id, variant_id (nullable)
- properties (json)  # flexible metadata (latency, error, device, etc.)

6) orders (optional but recommended)

Minimal order table for conversion tracking and pricing models. Avoid PII.

orders
- id (pk)
- client_id (fk)
- order_id (partner)
- created_at
- currency
- revenue_total
- items[]: [{ product_id, variant_id, qty, price }]
- attributed_session_id (nullable)
- attributed_job_id (nullable)

refunds (optional)
- id (pk)
- client_id (fk)
- order_id (partner)
- created_at
- amount
- reason_code (optional)

7) billing_usage

Aggregated usage for invoicing and monitoring.

billing_usage
- id (pk)
- client_id (fk)
- period_start, period_end
- tryon_jobs_succeeded
- tryon_jobs_failed
- unique_sessions
- overage_count
- estimated_cost_usd
- created_at

Partner data request checklist

What we ask the client to provide (wide list). Use this as onboarding.

  • Domains: prod + staging domains, allowed origins, CSP limits.
  • Catalog feed: product_id/variant_id/category, image URLs, price/currency, stock.
  • Placement: where widget appears (PDP/PLP/cart), languages, styling.
  • Attribution: add_to_cart + purchase events (GTM/pixel/webhook), minimal order payload.
  • Legal: consent requirements, retention, data processing constraints.
  • Business: expected traffic, pilot scope, baseline funnel metrics (optional).

Notes

  • This is a draft schema intended for implementation planning. Final tables may differ based on the partner’s platform and legal constraints.
  • For sensitive media (uploads/outputs), implement per-client retention and opt-in controls.