Testimony Workflow

This guide explains the complete testimony workflow from creation through completion, including all states, transitions, and available actions.

Overview

A testimony progresses through multiple states as clients and experts interact with it:

pending → offered → accepted → completed
   ↓         ↓
cancelled  cancelled

Workflow Stages

1. Pending - Awaiting Offers

Initial State: When a client creates a testimony, it starts in the pending state.

What This Means:

• Testimony is visible to experts serving the real estate's region (once geocoding has resolved it — see Create Testimony)
• No visible offers yet — offers from experts still awaiting approval stay hidden and leave the state untouched
• Experts can view it in offerable testimonies

Who Can Do What:

• Experts → Create offers with price and timeline
• Client → Cancel testimony

Possible Transitions:

• → offered when the first approved expert creates an offer, or when an expert holding a hidden offer on it gets approved
• → cancelled if client cancels

---

2. Offered - Receiving Expert Offers

Trigger: An expert creates an offer

What This Means:

• One or more experts have submitted offers
• Client can review and compare different offers
• Multiple experts can compete with different prices and timelines

Who Can Do What:

• Client → Initiate checkout for any offer
• Client → Cancel testimony
• Additional Experts → Create more offers

Possible Transitions:

• → accepted when client completes payment flow
• → cancelled if client cancels

Key Features:

• Multiple offers supported — one live offer per expert per testimony
• Offers from experts whose account is not yet approved stay hidden until approval — they surface (and the client is emailed) once the expert is approved
• Competitive pricing possible
• Client chooses preferred expert

---

3. Accepted - Work in Progress

Trigger: Client completes the payment flow

The acceptance process involves three steps:

1. Checkout Initiation

   • Client provides billing/shipping address
   • System creates Stripe checkout session
   • Client receives checkout URL

2. Payment on Stripe

   • Client completes payment on Stripe
   • Stripe processes the transaction
   • Commission is calculated

3. Payment Confirmation

   • Client confirms with Stripe session ID
   • Testimony transitions to accepted state
   • Expert is officially assigned

What This Means:

• Payment has been processed through Stripe
• Expert has been assigned to complete the work
• acceptedOffer field contains the chosen offer details
• expert field contains the assigned expert information
• Commission will be transferred to the platform

Who Can Do What:

• Expert → Upload final document

Possible Transitions:

• → completed when expert uploads the final document

Important Notes:

• Cannot be cancelled after payment (refund policies apply)
• Other offers are no longer relevant
• Only the assigned expert can complete the work

See Payment Integration Guide for detailed payment integration.

---

4. Completed - Work Delivered

Trigger: Expert uploads final testimony document

What This Means:

• Expert has uploaded the final PDF testimony
• Transaction is complete
• Client has access to the document
• Work appears in history for both parties

Who Can Do What:

• Client → Download testimony anytime
• Both → View in testimonies history

Possible Transitions:

• None (this is a final state)

---

5. Cancelled - No Longer Active

Trigger: Client or system cancels the testimony

What This Means:

• Testimony is no longer active
• No longer visible in active testimonies
• Cannot receive new offers or be accepted
• cancellationReason field may contain the reason

Who Can Cancel:

• Client → From pending or offered states
• System → In special edge cases

Cannot Be Cancelled:

• ❌ From accepted state (payment already completed)
• ❌ From completed state (work already finished)

Possible Transitions:

• None (this is a final state)

---

State Transition Reference

Current State	Next State	Trigger	Actor
pending	offered	Expert creates first offer	Expert
pending	cancelled	Client cancels	Client
offered	accepted	Payment completed	Client
offered	cancelled	Client cancels	Client
accepted	completed	Expert uploads document	Expert

State Flow Diagram

                            ┌─────────┐
                            │ pending │
                            └────┬────┘
                                 │
                  ┌──────────────┴──────────────┐
                  │                             │
      [first offer created]             [client cancels]
                  │                             │
                  ↓                             │
             ┌─────────┐                        │
             │ offered │                        │
             └────┬────┘                        │
                  │                             │
           ┌──────┴──────┐                      │
           │             │                      │
    [payment      [client cancels]              │
    completed]           │                      │
           │             └──────────────┬───────┘
           │                            │
           ↓                            ↓
      ┌──────────┐                ┌───────────┐
      │ accepted │                │ cancelled │
      └────┬─────┘                └───────────┘
           │                         (final)
           │
[expert uploads document]
           │
           ↓
     ┌───────────┐
     │ completed │
     └───────────┘
       (final)

Common Scenarios

Happy Path

1. Client creates testimony (pending)
2. Expert creates offer (offered)
3. Client completes payment (accepted)
4. Expert uploads document (completed)
5. Client downloads testimony

Early Cancellation

1. Client creates testimony (pending)
2. Client decides not to proceed
3. Client cancels (cancelled)

Multiple Offers

1. Client creates testimony (pending)
2. Expert A creates offer (offered)
3. Expert B creates offer (still offered)
4. Expert C creates offer (still offered)
5. Client chooses Expert B's offer
6. Client completes payment (accepted with Expert B)

State Properties

Pending State

• state: "pending"
• expert: null
• acceptedOffer: null
• Visible in offerable testimonies list

Offered State

• state: "offered"
• expert: null
• acceptedOffer: null
• Has one or more associated offers

Accepted State

• state: "accepted"
• expert: Assigned expert object
• acceptedOffer: Chosen offer object
• Payment completed

Completed State

• state: "completed"
• expert: Assigned expert object
• acceptedOffer: Chosen offer object
• Document available for download

Cancelled State

• state: "cancelled"
• cancellationReason: Optional reason string