> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valiyou.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Proposals

> Send sponsorship proposals to sponsors, track approval status, and manage branded PDF documents. Generate proposals with digital signatures and auto-tracking.

# Sponsorship Proposals & Tracking

<iframe className="w-full aspect-video rounded-xl" src="https://player.mux.com/02gk5IuFRKbrMw2IatteL00z2CzhJ4she5HNQG2b1St5g" title="Valiyou Proposals walkthrough" allowFullScreen />

**Send professional sponsorship proposals and track sponsor decisions in real-time.** Generate branded PDF documents, monitor proposal status, track email opens and approvals, collect digital signatures, and manage the complete proposal lifecycle from send to contract with comprehensive audit trails.

View all sent sponsorship proposals, track their status, review audit trails, and monitor sponsor decisions in real-time.

## Accessing Proposals

Navigate to **Sponsorships** → **Proposals** from the sidebar to access sent proposals and track sponsor responses.

<Note>
  **Plan Required**: Professional or Enterprise plan **Permission Required**: Proposals permission
  or Admin access
</Note>

## What Are Proposals?

Proposals are packages that have been sent to sponsors for review and approval. When you send a package from Package Builder, it moves from the Packages page to the Proposals page.

**Proposal Lifecycle:**

1. **Draft** - Package created but not sent (shows in Packages page)
2. **Pending Approval** - Sent to sponsor, awaiting response (shows in Proposals page)
3. **Approved** - Sponsor accepted the proposal (shows in Proposals page)
4. **Rejected** - Sponsor declined the proposal (shows in Proposals page)
5. **Expired** - Proposal deadline passed without response (shows in Proposals page)

<Info>
  **Lifecycle Tracking**: Each proposal maintains complete history from creation through final
  decision, with timestamps, IP addresses, and sponsor actions recorded for compliance and analysis.
</Info>

## Proposals List Page

### Empty State

If you haven't sent any proposals yet, you'll see:

* **Icon**: Document graphic
* **Title**: "No pending packages"
* **Message**: "Generate proposals from your packages to send to sponsors for approval."
* **Action**: "Go to Packages" button

<Tip>
  **Getting Started**: Create a package in Packages page, build inclusions, then use "Send Proposal"
  to generate your first proposal.
</Tip>

### Proposals List

Vertical list of all sent proposals sorted by sent date (newest first).

#### List Item Layout

Each proposal displays:

**Left Side:**

* **Sponsor Logo**: 48\*48px square (or document icon fallback)
* **Sponsor Name**: Bold, clickable
* **Package Tier**: Below name (e.g., "Gold", "Platinum")
* **Sales Price**: Currency formatted (hidden in Negotiator Mode)

**Right Side (Desktop):**

* **Package Name**: Bold
* **Sent Date**: "Sent \[date]" (e.g., "Sent Jan 15, 2025")
* **Expires Date**: "Expires \[date]"
* **Status Badge**: Visual indicator with color dot

**Chevron**: Right-facing arrow indicating clickable item

<Info>**Click Anywhere**: The entire row is clickable and opens the proposal preview page.</Info>

### Status Badges

Four status types with colored indicators:

#### Pending

**Color**: Amber/Yellow
**Dot**: Amber circle
**Label**: "Pending"
**Meaning**: Sent to sponsor, waiting for response
**Shows**: Before expiration date

#### Approved

**Color**: Green
**Dot**: Green circle
**Label**: "Approved"
**Meaning**: Sponsor accepted the proposal
**Shows**: After sponsor approval

#### Rejected

**Color**: Red
**Dot**: Red circle
**Label**: "Rejected"
**Meaning**: Sponsor declined the proposal
**Shows**: After sponsor rejection

#### Expired

**Color**: Gray
**Dot**: Gray circle
**Label**: "Expired"
**Meaning**: Deadline passed without response
**Shows**: After expiration date (still pending)

<Warning>
  **Expiration**: Expired proposals remain in "pending" status but are marked as expired. Sponsors
  can no longer accept expired proposals via the proposal link.
</Warning>

### Sorting

**Order**: Newest first (by sent date)
**Logic**: Most recently sent proposals appear at the top
**Fixed**: No manual sorting or filtering options

## Proposal Preview Page

Detailed view of a single proposal with PDF preview and audit trail.

### Accessing Preview

**From List**: Click on any proposal in the list
**Direct URL**: `/products/sponsorships/packages/[id]/preview`

### Page Layout

Split-screen layout:

**Left Side (Main):**

* Full PDF preview
* Download button

**Right Side (Sidebar):**

* Proposal Preview header
* Status badge
* Audit trail
* Action buttons

<Info>**Responsive**: On mobile, sidebar appears above PDF for better UX.</Info>

### PDF Preview

**Display**: Embedded PDF viewer
**Content**: Exact proposal PDF sent to sponsor
**Features**:

* Scroll to view all pages
* Zoom controls
* Fullscreen option (browser-dependent)

**Loading States**:

* Shows spinner while PDF loads
* Error message if PDF fails to load
* Retry option on error

<Tip>
  **Same as Sent**: This is the exact PDF the sponsor received via email. Use it to verify proposal
  contents after sending.
</Tip>

### Status Badge (Detailed)

Expanded status information:

**Pending Approval:**

* Icon: Clock
* Color: Amber
* Label: "Pending Approval"
* Sub-text: "Awaiting sponsor response"

**Approved:**

* Icon: Check Circle
* Color: Green
* Label: "Approved"
* Sub-text: "Accepted on \[date]"

**Rejected:**

* Icon: X Circle
* Color: Red
* Label: "Rejected"
* Sub-text: "Declined on \[date]"

**Expired:**

* Icon: Clock
* Color: Gray
* Label: "Expired"
* Sub-text: "Expired on \[date]"

### Audit Trail

Chronological timeline of proposal events.

#### Timeline Events

**1. Proposal Sent**:

* Icon: Envelope
* Label: "Proposal Sent"
* Date: Sent date and time
* Details: Sent to \[contact emails]
* Shows: Always (first event)

**2. Proposal Opened** (if tracking enabled):

* Icon: Eye
* Label: "Proposal Opened"
* Date: First open timestamp
* Details: Opened by \[IP address]
* Shows: If sponsor opened email

**3. Sponsor Response**:

* **Approved**:
  * Icon: Check Circle (green)
  * Label: "Proposal Approved"
  * Date: Approval date and time
  * Details: Approved by \[contact name]
  * Value: Package value shown
* **Rejected**:
  * Icon: X Circle (red)
  * Label: "Proposal Rejected"
  * Date: Rejection date and time
  * Details: Rejected by \[contact name]

**4. Signature Data** (if signed):

* Icon: Pen
* Label: "Digitally Signed"
* Details:
  * Signer name, title, company
  * Signed date and time
  * IP address
* Shows: If sponsor signed electronically

**5. Expiration**:

* Icon: Clock (gray)
* Label: "Proposal Expired"
* Date: Expiration date
* Details: "No response received"
* Shows: If expired without response

<Info>
  **Chronological Order**: Events appear in timeline order from top (most recent) to bottom
  (oldest).
</Info>

### Action Buttons

Located in sidebar panel.

#### Edit Package (Pending/Draft only)

**Button**: "Edit Package" with pencil icon
**Visibility**: Shows only for pending or draft proposals
**Action**: Navigates to Package Builder
**Use Case**: Make changes before sponsor responds

<Warning>
  **After Approval**: Edit button is hidden for approved proposals. You cannot edit an approved
  package.
</Warning>

#### Download PDF

**Button**: "Download PDF" with download icon
**Visibility**: Always visible
**Action**: Downloads proposal PDF to computer
**Filename**: `proposal-[package-name].pdf`
**Use Case**: Save for records, print, or share internally

#### Resend Proposal (Coming Soon)

**Button**: "Resend" with envelope icon
**Visibility**: Shows for expired or pending proposals
**Action**: Re-sends proposal email to contacts
**Use Case**: Remind sponsor, send to additional contacts

### Proposal Information Panel

Additional details shown in sidebar:

**Sent To:**

* List of recipient email addresses
* Primary contact highlighted
* Shows all recipients from original send

**Package Details:**

* Package name
* Package tier badge
* Sales price (if not Negotiator Mode)
* Event assignments (if any)

**Expiration Info:**

* "Expires on \[date]" (if pending)
* "Expired on \[date]" (if expired)
* Countdown timer (optional, if pending)

<Tip>
  **Track Progress**: Check audit trail regularly to see if sponsors opened the proposal. This helps
  with follow-up timing.
</Tip>

## Proposal Status Management

### Status Transitions

Valid status flows:

```
draft → pending_approval → approved
                        → rejected
                        → expired (after deadline)
```

**Cannot Go Backward**: Once approved/rejected, status is final
**Expired Can't Approve**: Expired proposals can't be accepted by sponsor

### Automatic Status Updates

**Sent**: Status changes to "pending\_approval" when email is sent
**Approved**: Status changes to "approved" when sponsor clicks "Accept"
**Rejected**: Status changes to "rejected" when sponsor clicks "Decline"
**Expired**: Status remains "pending\_approval" but badge shows "Expired"

<Info>
  **Real-Time Updates**: Refresh the page to see latest status changes from sponsor actions.
</Info>

## Sponsor Approval via Email

### How Sponsors Receive Proposals

When you send a proposal, sponsors receive an email containing:

**Email Contents**:

* Subject line with your organization name and package name
* Personalized greeting with sponsor contact name
* Brief introduction to the sponsorship package
* Package tier and sales price (if not Negotiator Mode)
* Unique proposal link button
* Expiration date reminder
* Contact information for questions

**Proposal Link**:

* Format: `https://yourorg.valiyou.com/proposal/[token]`
* Token: Unique, secure, non-guessable identifier
* Access: No login required (public link)
* Expires: After the expiration date set in package

<Warning>
  **Security**: Proposal links are public but unguessable tokens. Don't share links publicly. Only
  send to intended sponsor contacts via the Send Proposal feature.
</Warning>

### External Approval Page

Split-screen interface designed for sponsor decision-making:

**Layout**:

* **Left Side (75%)**: Full PDF preview of proposal
* **Right Side (25%)**: Signing panel with approval form

**Mobile Layout**:

* PDF preview on top (full width)
* Signing panel below (full width)
* Scrollable content

### Signing Panel (Right Side)

Fixed panel with all approval controls.

#### Header Section

**Organization Branding**:

* Organization logo (48\*48px)
* "Sponsorship Proposal" title
* "From \[Organization Name]" subtitle
* White background

#### Signer Information Form

**Section Title**: "Entitled to draw"

**Required Fields**:

1. **Full Name** - Text input for signer's full name
2. **Job Title** - Text input for position/role
3. **Company** - Pre-filled with sponsor name (editable)

**Validation**:

* All fields required before approval
* Empty fields prevent submission
* Error message shown if incomplete

<Tip>
  **Pre-filled Company**: The company field is automatically filled with the sponsor name but can be
  edited if needed.
</Tip>

#### Approval Consent Checkbox

**Section Title**: "Approval Consent"

**Checkbox Text**:
"I confirm that I am authorized to approve this sponsorship on behalf of \[Company Name], that I have reviewed the complete package, and that I accept the terms and agree to pay \[Sales Price] for this package."

**Features**:

* Single comprehensive consent checkbox
* Dynamic company name (from Company field)
* Dynamic sales price display
* Must be checked to approve
* Unchecked by default

**Legal Compliance**:

* Records consent timestamp
* Captures IP address
* Stores user agent (browser/device info)
* Creates SHA-256 hash of package snapshot for integrity

#### Download PDF Link

**Location**: Below consent checkbox, above action buttons

**Link Text**: "Download proposal as PDF" with download icon

**Action**:

* Fetches PDF from API via proposal token
* Creates blob and triggers browser download
* Filename: `[Package_Name]_Proposal.pdf`
* Allows sponsor to save proposal before deciding

<Info>
  **Download First**: Sponsors can download the proposal PDF to share internally or review offline
  before making a decision.
</Info>

#### Action Buttons

Fixed at bottom of signing panel.

**Approve Package Button**:

* **Style**: Primary blue button, full width
* **Text**: "Approve Package" with check icon
* **State**: Disabled until form is valid (all fields filled + consent checked)
* **Loading**: Shows spinner when submitting
* **Action**: Submits approval with signature data

**Decline Proposal Button**:

* **Style**: Secondary gray button, full width
* **Text**: "Decline Proposal"
* **State**: Always enabled (no form validation required)
* **Loading**: Shows spinner when submitting
* **Action**: Submits rejection (optional signer info if provided)

**Validation Message**:

* Shows below buttons if submission attempted with incomplete form
* Text: "Please complete all required fields and checkboxes"
* Red text, center-aligned

### PDF Preview (Left Side)

Embedded PDF viewer showing exact proposal sent via email.

**Features**:

* Full-page PDF display
* Scroll to view all pages
* Zoom controls (browser-native)
* Same PDF as downloaded version

**Content**:

* Organization header and logo
* Sponsor name and logo
* Package tier and pricing
* Inclusions table with quantities and costs
* Terms and conditions
* Total package value

### Approval Flow

Step-by-step process when sponsor approves:

**1. Sponsor Clicks Approve Button**:

* Form validation runs
* Check all required fields
* Check consent checkbox
* Show error if incomplete

**2. Submit Approval to API**:

* POST request to `/api/products/sponsorships/proposal/[token]`
* Body includes:
  * `action: 'approve'`
  * `signature.signer`: Name, title, company
  * `signature.consent`: All consent data with timestamp

**3. Server Validation**:

* Verify proposal token exists
* Check proposal hasn't expired
* Confirm status is "pending\_approval" (not already responded)
* Validate signature data provided

**4. Capture Audit Trail**:

* IP address from request headers
* User agent (browser/device info)
* Timestamp of signature
* SHA-256 hash of package snapshot for data integrity

**5. Update Package Status**:

* Change status from "pending\_approval" to "approved"
* Store signature data (signer info + consent + audit trail)
* Clear expiration date (no longer relevant)
* Keep proposal token active (for confirmation page)

**6. Show Success Modal**:

* Green checkmark icon
* "Proposal Approved" title
* Thank you message
* "Your digital signature has been recorded..." note
* Download proposal link
* Modal overlays entire page

**Signature Data Stored**:

```json theme={null}
{
  "signer": {
    "name": "John Doe",
    "title": "Marketing Director",
    "company": "Sponsor Corp"
  },
  "consent": {
    "reviewed_package": true,
    "authorized_to_sign": true,
    "accept_terms": true,
    "acceptance_timestamp": "2025-01-15T14:30:00.000Z"
  },
  "audit_trail": {
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0...",
    "signed_at": "2025-01-15T14:30:00.000Z",
    "package_snapshot_hash": "sha256:abc123..."
  }
}
```

### Rejection Flow

Simplified process when sponsor declines:

**1. Sponsor Clicks Decline Button**:

* No form validation required
* Can decline even without filling form
* Confirmation immediate (no additional modal)

**2. Submit Rejection to API**:

* POST request to `/api/products/sponsorships/proposal/[token]`
* Body includes:
  * `action: 'reject'`
  * `signature.signer`: Optional (if name provided, includes it)

**3. Server Processing**:

* Verify proposal token and expiration
* Confirm status is "pending\_approval"
* No signature data validation required

**4. Update Package Status**:

* Change status from "pending\_approval" to "rejected"
* Store minimal signer info (if provided)
* Clear expiration date
* Keep proposal token active

**5. Show Declined Modal**:

* Red X icon
* "Proposal Declined" title
* "You have declined the sponsorship package..." message
* "The organization has been notified" confirmation
* Modal overlays entire page

<Info>
  **No Form Required**: Sponsors can decline without filling any fields. Signer information is
  optional for rejections.
</Info>

### Post-Response States

What happens after sponsor responds:

**Proposal Already Approved**:

* Shows success modal immediately on page load
* Green checkmark with "Proposal Approved" message
* Download PDF link available
* Prevents duplicate submissions

**Proposal Already Rejected**:

* Shows declined modal immediately on page load
* Red X with "Proposal Declined" message
* Organization notified text
* Prevents duplicate submissions

**Proposal Expired**:

* Yellow clock icon
* "Proposal Expired" title
* Message: "This proposal link has expired. Please contact the organization for a new proposal."
* No form or buttons shown

**Proposal Not Found**:

* Red error icon
* "Error Loading Proposal" title
* Generic error message
* No form or buttons shown

### Security and Compliance

**Data Integrity**:

* Package snapshot hash (SHA-256) ensures proposal wasn't modified after signing
* Hash includes: package ID, name, sales price, cost price, items
* Prevents tampering and provides legal proof

**Audit Trail**:

* IP address capture (x-forwarded-for header)
* User agent capture (browser/device info)
* Timestamp in ISO 8601 format
* All data stored in `signature_data` JSONB column

**Legal Compliance**:

* Digital signature with explicit consent
* Timestamp and IP for non-repudiation
* Package snapshot hash for integrity
* Audit trail for legal documentation

**Privacy**:

* No user account required (public link)
* Minimal data collection (only what's needed for signature)
* Secure token prevents unauthorized access
* Expiration date limits exposure window

<Warning>
  **Legal Weight**: The digital signature with consent, timestamp, IP, and package hash provides
  legally binding documentation of approval. Treat approval seriously.
</Warning>

## Permissions

Different permissions show different content:

| Permission         | Can View List | Can View Preview | Can Edit             | Can Resend |
| ------------------ | ------------- | ---------------- | -------------------- | ---------- |
| **Proposals Role** | ✅ Yes         | ✅ Yes            | ✅ Yes (pending only) | ✅ Yes      |
| **Admin**          | ✅ Yes         | ✅ Yes            | ✅ Yes (pending only) | ✅ Yes      |
| **Other Roles**    | ❌ No          | ❌ No             | ❌ No                 | ❌ No       |

<Info>
  **Professional/Enterprise Only**: Proposals feature requires Professional or Enterprise plan.
  Starter plans cannot access this module.
</Info>

## Common Use Cases

### Monitoring Sent Proposals

1. Open Proposals page
2. Review list for pending proposals
3. Click on specific proposal
4. Check audit trail for opens/actions
5. Follow up if no response after several days

### Verifying Proposal Contents

1. Click on proposal from list
2. Review PDF preview
3. Verify all items, quantities, pricing
4. Check terms and conditions
5. Confirm correct sponsor information

### Following Up on Pending

1. Check sent date in list
2. Review audit trail for opens
3. Wait appropriate time (3-7 days)
4. Use audit trail to time follow-up
5. Resend or contact sponsor directly

### Handling Approvals

1. See "Approved" badge in list
2. Open proposal preview
3. Review approval timestamp
4. Check signature data (if provided)
5. Download PDF for records
6. Proceed with contract finalization

### Managing Rejections

1. See "Rejected" badge in list
2. Open proposal preview
3. Review rejection timestamp
4. Check audit trail for context
5. Follow up with sponsor for feedback
6. Create revised package if needed

### Dealing with Expirations

1. See "Expired" badge in list
2. Open proposal preview
3. Check if sponsor opened (audit trail)
4. Resend with extended deadline
5. Or contact sponsor directly

## Troubleshooting

### Proposal Not Showing in List

**Check**:

* Proposal was sent (not still draft)
* You have Proposals permission
* Refresh page to update list
* Check Packages page (might be draft)

### PDF Preview Won't Load

**Try**:

* Refresh page
* Clear browser cache
* Check network connection
* Try different browser
* Contact support if persists

### Status Not Updating

**Fix**:

* Refresh page manually (status updates on refresh)
* Check sponsor received link
* Verify link wasn't expired when sponsor clicked
* Check spam folder for bounce emails

### Can't Edit Proposal

**Reasons**:

* Proposal is approved (can't edit)
* Proposal is rejected (can't edit)
* Don't have edit permissions
* Network error

**Solution**:

* Create new package for approved/rejected
* Request permissions from admin
* Check browser console for errors

### Download PDF Fails

**Try**:

* Disable popup blocker
* Allow file downloads in browser
* Check disk space
* Try different browser
* Use "Print to PDF" as alternative

## Frequently Asked Questions

### How do I send a sponsorship proposal?

Create a package in the Packages page, add inventory items and set pricing, click "Send Proposal" button, enter sponsor contact emails, set expiration date, and click send. The system generates a branded PDF and emails it to the sponsor with a unique approval link.

### Can I track when sponsors open proposals?

Yes, the audit trail shows when sponsors open proposal emails (if tracking is enabled) including timestamp and IP address. Check the proposal preview page audit trail section to see "Proposal Opened" event with date, time, and location details.

### What happens when a sponsor approves?

When a sponsor approves, the status changes to "Approved," signature data is recorded (name, title, company, timestamp, IP), audit trail captures approval event, and you receive notification. Download the approved proposal PDF with signature data for contract finalization.

### How long do proposal links stay active?

Proposal links expire on the date you set when sending the proposal. After expiration, sponsors see an "Expired" message and cannot approve. The link remains accessible for viewing but approval buttons are disabled. Resend proposals to extend deadlines.

### Can I edit a proposal after sending?

You can edit pending proposals before sponsor responds by clicking "Edit Package" in the proposal preview. After approval or rejection, proposals are locked and cannot be edited. Create a new package for changes to approved or rejected proposals.

### What if a sponsor doesn't respond?

If a sponsor doesn't respond, check the audit trail to see if they opened the proposal, wait 3-7 days before following up, use the "Resend" button to send a reminder, or contact them directly via phone or email to discuss the proposal.

### How do digital signatures work?

Digital signatures require sponsor to fill in name, job title, and company, check consent checkbox confirming authorization and agreement, and click "Approve Package" button. The system captures IP address, timestamp, and browser details, creating legally binding approval documentation with SHA-256 package hash.

### Can I customize the proposal PDF?

Yes, proposal PDFs automatically include your organization logo and branding, sponsor information and contact details, package name, tier, and pricing, inventory items with quantities and costs (unless Negotiator Mode), and custom terms and conditions. Configure branding in organization settings.

### What's the difference between Packages and Proposals?

Packages are draft sponsorship bundles being built in Package Builder that haven't been sent. Proposals are packages that have been sent to sponsors for approval and appear in the Proposals page with tracking, status badges, and audit trails.

### How do I generate proposal reports?

Export proposal data by downloading individual PDFs from proposal preview pages, using analytics dashboard (Professional/Enterprise plans) to view acceptance rates, exporting proposal lists to CSV for custom analysis, and scheduling automated reports for team and stakeholder distribution.

## Next Steps

<CardGroup cols="2">
  <Card title="Monitor Responses" icon="inbox" href="/sponsorships/proposals#proposal-statuses">
    Check proposals daily for sponsor decisions
  </Card>

  <Card title="Follow Up" icon="phone" href="/sponsorships/sponsors#contacts">
    Contact sponsors after 3-7 days if no response
  </Card>

  <Card title="Analyze Performance" icon="chart-line" href="/sponsorships/analytics">
    Review proposal success rates and metrics
  </Card>

  <Card title="Refine Packages" icon="box" href="/sponsorships/packages">
    Use approval data to optimize future packages
  </Card>

  <Card title="Manage Contracts" icon="file-signature" href="/sponsorships/sponsors#sponsor-details">
    Move approved proposals to contract finalization
  </Card>
</CardGroup>

<Tip>
  **Best Practice**: Set up email notifications (if available) to get instant alerts when sponsors
  approve or reject proposals. This enables immediate follow-up.
</Tip>