Initial commit: nick docs

06 - Usage/Seller Guide.md

@@ -0,0 +1,365 @@
+---
+title: Seller Guide
+tags: [usage, role/seller, role/owner]
+audience: Seller (Owner)
+created: 2026-05-23
+---
+
+# Seller Guide (Owner)
+
+End-to-end usage for a **Seller** (Shop Owner) — the person who responds to buyer purchase requests, fulfils orders, and withdraws escrow funds.
+
+> [!info]
+> Looking for a different role? See [[User Guide]] (Buyer), [[Admin Guide]], [[Support Guide]].
+
+---
+
+## 1. Becoming a Seller
+
+You can either:
+
+- **Sign up as Seller** at registration (`/auth/jwt/sign-up` → choose role = Seller).
+- **Upgrade from Buyer**: existing buyer → **Dashboard → Account → Become a seller** → submit shop info → admin verification.
+
+Either path requires:
+
+- Verified email
+- Phone number on file (some regions require KYC)
+- Initial shop info (name, country, payout wallet address)
+
+---
+
+## 2. Configuring your shop
+
+### 2.1 Shop branding
+
+**Dashboard → Shop Settings → Settings**:
+
+| Field | Notes |
+|---|---|
+| Shop name | Public; shown in shop URL `/shop/{slug}` |
+| Tagline | One-line summary on the shop card |
+| About | Rich-text editor (use the editor for headings, lists, links) |
+| Avatar / logo | 256×256 recommended |
+| Cover image | 1600×400 recommended |
+| Category specialisations | Tag your shop with categories you cover |
+| Country / Region | Used for delivery filters |
+| Default response time | "I usually respond within X hours" |
+| Default delivery window | "Typical fulfilment 3–5 business days" |
+
+### 2.2 Social links
+
+**Shop Settings → Socials**: Twitter, Instagram, Telegram, website. Shown on your public shop page.
+
+### 2.3 Security
+
+**Shop Settings → Security**:
+- Withdraw confirmation requires email code (recommended)
+- Two-factor authentication
+- Login alerts
+
+### 2.4 Payout wallet
+
+**Account → Wallet** or **Shop Settings → Payout**:
+
+- Add a crypto address you control on the supported networks (BSC, Polygon, …).
+- All payouts (escrow releases) go here.
+- You can change it, but new payouts go to the new address — past payouts are settled to whichever address was active at the time.
+
+> [!warning]
+> Your payout address is the **single source of funds out of escrow**. Triple-check it. If it's wrong, funds can be irretrievably lost.
+
+---
+
+## 3. Request Templates
+
+Templates are pre-defined product/service offerings. Buyers can create a request from your template with one click.
+
+### 3.1 Create a template
+
+**Dashboard → Request Templates → + New**:
+
+1. **Title** — what you sell ("Vintage leather jacket", "Custom logo design").
+2. **Category** — primary category.
+3. **Description** — rich text, use images.
+4. **Pricing** — fixed price or "starts at" range. Specify currency.
+5. **Delivery window** — typical days from acceptance.
+6. **Customisations** — list of options (size, color, quantity) buyers can choose.
+7. **Videos** (optional) — embed up to N video URLs.
+8. **Default proposal** — your standard offer text that auto-populates when a buyer creates from this template.
+9. **Expiration** — leave blank for evergreen; set a date for limited-time offers.
+10. **Visibility** — public (anyone can use) or unlisted (shareable URL only).
+
+Click **Publish**. You'll get a shareable URL: `https://amn.gg/shop/{seller}/{templateId}`.
+
+### 3.2 Manage templates
+
+**Dashboard → Request Templates** shows all templates with:
+
+- Status (active / expired / draft)
+- Usage count (how many buyers used it → became a real request)
+- Conversion rate (used → accepted)
+- Quick edit / clone / disable
+
+See [[RequestTemplate]] and [[Purchase Request Flow]].
+
+---
+
+## 4. Finding open buyer requests
+
+Once your shop is configured, you can browse incoming buyer demand.
+
+### 4.1 Public requests
+
+**Dashboard → Shops → Browse** (or via the marketplace surface):
+
+- Filter by category, budget range, delivery deadline, buyer location.
+- Sort by recency, budget, urgency.
+- Click a request for details.
+
+### 4.2 Invited requests
+
+If a buyer specifically invites you (often via a template URL), the request appears under **Dashboard → Requests → Invited**.
+
+### 4.3 Notifications
+
+- New public request matching your specialisation → notification + email (if enabled).
+- Direct invitation → push notification.
+
+---
+
+## 5. Submitting an offer
+
+On a request detail page → **Submit offer**:
+
+1. **Your price** (in the buyer's requested currency).
+2. **Delivery window** (days from acceptance).
+3. **Notes** (rich text — explain your approach, materials, brand, etc.).
+4. **Attachments** (optional — photos of work samples, references).
+5. **Expire offer in** (default 7 days) — after which the offer auto-rejects.
+
+Click **Send offer**. The buyer is notified instantly via socket.
+
+> [!tip]
+> Offers with personalised notes convert ~3× better than generic ones. Show the buyer you read their request.
+
+See [[Seller Offer Flow]].
+
+---
+
+## 6. Negotiating
+
+The buyer may message you to discuss:
+
+- Lowering your price
+- Faster delivery
+- Customisations not in your template
+
+You can:
+
+1. **Reply via chat** to explain or negotiate.
+2. **Issue a counter-offer** — opens a new offer slot replacing your previous one.
+3. **Accept their counter-proposal** if they sent one.
+
+See [[Negotiation Flow]].
+
+---
+
+## 7. Acceptance — what happens
+
+When the buyer accepts your offer:
+
+1. All other sellers' offers on this request are auto-rejected.
+2. Status moves to **Accepted**.
+3. The buyer is prompted to pay into escrow.
+4. You receive a notification.
+5. You can prepare to fulfil — but **DO NOT ship until escrow is funded**.
+
+> [!warning]
+> Shipping before funding = you have no recourse if buyer never pays. Always wait for status = **Funded**.
+
+---
+
+## 8. Fulfilment
+
+Once status = **Funded**:
+
+1. Prepare the item / service.
+2. On the request page → click **Mark as shipped**.
+3. Optionally add:
+   - Tracking number + carrier
+   - Photos of packed item
+   - Notes for buyer
+4. The buyer is notified.
+
+For digital goods (designs, files): upload via the request's **Deliverables** section. Buyer is notified to confirm.
+
+See [[Delivery Confirmation Flow]].
+
+---
+
+## 9. Getting paid
+
+When the buyer confirms receipt → status = **Delivered** → escrow released.
+
+> [!important]
+> Today, escrow release after confirmation triggers a **payout request** which an admin manually processes. See [[Payout Flow]]. Payouts typically clear within 1–2 business days.
+
+### 9.1 Withdraw
+
+**Dashboard → Payment → Payouts** lists pending and processed payouts.
+
+For self-service withdrawal (if enabled):
+
+1. Click **Request payout**.
+2. Confirm your payout wallet address.
+3. Enter the amount (≤ available balance).
+4. Submit.
+5. Status moves through **pending → processing → completed**.
+
+Once **completed**, you'll see the on-chain transaction hash linking to a block explorer.
+
+---
+
+## 10. Disputes
+
+If a buyer opens a dispute:
+
+1. You're notified immediately.
+2. **The escrow is paused** — neither party can move funds until the dispute resolves.
+3. Open the dispute page → review the buyer's claim and evidence.
+4. **Submit your evidence**: photos (e.g., shipped item, packaging proof), chat screenshots, tracking confirmation.
+5. Write a clear response narrative.
+6. An **admin mediator** reviews both sides and issues a decision.
+
+Possible outcomes:
+
+- **Full refund to buyer** (dispute upheld) — you lose the sale + may lose listing if pattern.
+- **Partial refund** — split.
+- **Release to you** (dispute denied) — full payout proceeds.
+- **Mutual cancellation** — agreed refund.
+
+Tips to win disputes:
+
+- Always include proof of shipping with timestamp.
+- Save chat screenshots (the platform retains them, but redundant proof helps).
+- Respond to disputes within 24 hours.
+- Don't argue with the buyer publicly in chat — let the mediator decide.
+
+See [[Dispute Flow]].
+
+---
+
+## 11. Reviews
+
+After each completed transaction:
+
+- Buyer rates you (1–5 stars + comment).
+- You rate the buyer.
+
+Your overall rating is shown on every offer you make. Common rating thresholds:
+
+- **4.8+** — Top-rated badge, priority listing
+- **4.0–4.7** — Normal
+- **<4.0** — Limited visibility, manual review may follow
+
+Respond to negative reviews professionally — your reply is public.
+
+---
+
+## 12. Analytics
+
+**Dashboard → Overview** shows your seller KPIs:
+
+| Metric | Description |
+|---|---|
+| Open requests | Active conversations |
+| Acceptance rate | Offers accepted / submitted |
+| Avg. response time | How fast you reply |
+| Avg. delivery time | From accept to ship |
+| Revenue (30/90/365 days) | Net of fees |
+| Active templates | Live request templates |
+| Rating | Current overall stars |
+| Dispute rate | % of orders disputed |
+
+Improve weak areas to climb the seller leaderboard.
+
+---
+
+## 13. Earning points (Seller side)
+
+Sellers earn points for:
+
+- Each successful sale
+- Maintaining high rating
+- Fast response times
+- Referring other sellers / buyers
+
+Points unlock benefits — see [[User Guide]] §12 and [[LevelConfig]].
+
+---
+
+## 14. Settings
+
+Same as Buyer (theme, language, notifications, security) plus:
+
+- **Auto-decline** new requests when busy (set a date range).
+- **Vacation mode** — pause public visibility without losing offers in flight.
+- **Tax info** — if applicable in your jurisdiction.
+
+---
+
+## 15. Common issues
+
+### "My offer isn't getting acceptance"
+
+- Compare your price to similar offers (visible in the request side panel).
+- Improve your **default response time** & rating.
+- Add personalised notes to each offer.
+- Use rich descriptions in templates.
+
+### "Escrow funds not showing up after delivery"
+
+> [!warning]
+> Auto-release on delivery confirmation is **not yet automated** — an admin manually triggers payouts on a schedule. Allow 1–2 business days.
+
+If it's been longer, contact support.
+
+### "Wrong payout address"
+
+If you noticed a wrong address BEFORE the payout was sent → update in **Shop Settings → Payout** and contact support.
+
+If the payout was already broadcast → recovery requires on-chain coordination; contact support immediately with the transaction hash.
+
+### "Dispute opened — what to do first"
+
+1. Don't panic.
+2. Read the buyer's claim carefully.
+3. Gather all proof (shipping receipts, photos, chat history).
+4. Submit evidence within 24 hours.
+5. Be respectful in your narrative.
+
+### "Need to take time off"
+
+Set **Vacation mode** in Shop Settings. New requests auto-decline with a courteous message; existing orders proceed normally.
+
+---
+
+## 16. Tips & best practices
+
+> [!tip]
+> - **Reply fast** — first responder often wins.
+> - **Photos sell** — clear, well-lit images convert.
+> - **Be specific in delivery dates** — buyers value predictability.
+> - **Use templates** for repeat offerings — saves time, increases conversion.
+> - **Build a portfolio in your shop About** — recent work, certifications.
+> - **Respond to ALL reviews** — even one-line "Thank you" helps.
+
+---
+
+## 17. Related
+
+- [[User Guide]] · [[Admin Guide]] · [[Support Guide]]
+- Flows: [[Seller Offer Flow]] · [[Negotiation Flow]] · [[Delivery Confirmation Flow]] · [[Payout Flow]] · [[Dispute Flow]] · [[Rating Flow]]
+- Models: [[User]] · [[RequestTemplate]] · [[SellerOffer]] · [[ShopSettings]] · [[Review]]
+- [[Glossary]]