Vendor Engagements

How to track and account for external agencies and contractors paid on a fixed-fee basis.

---

When to use this workflow

Use vendor engagements when you're paying an external party a fixed amount for a defined deliverable — e.g.:

• "We're paying Dev House X $5,000 to build the authentication module"
• "Freelancer Y is handling all copywriting on this project for $2,000"
• "Design agency Z is delivering the rebrand at a flat fee of $15,000"

This is different from an hourly contractor tracked through Rate History. Vendors have a fixed agreed_amount that overrides the hours × rate calculation entirely.

---

Step 1: Add the vendor as a user

"Add user 'Dev House X' with employment type vendor"

add_user
  user_name: "Dev House X"
  employment_type: "vendor"
  role: "user"

Vendors appear in list_users like regular team members. They can be allocated to projects and have time logged against them. They won't message the bot themselves — PMs log on their behalf.

---

Step 2: Create a liability

"Create a liability for Dev House X on Project Rambo for $5,000 — authentication module development"

create_liability
  project_name: "Project Rambo"
  vendor_name: "Dev House X"
  agreed_amount: 5000
  description: "Authentication module development"

Owner only. The vendor must have employment_type = "vendor".

This registers the fixed payment commitment. From this point, VERA uses $5,000 as the cost for Dev House X on Project Rambo — regardless of how many hours are logged.

---

Step 3: PM logs hours for the vendor

As the vendor delivers work, the PM logs hours on their behalf:

"Log 8h for Dev House X on Project Rambo — Development"

Hours flow into revenue calculations normally. Cost comes from the liability.

---

Step 4: View financials

"Show liabilities for Project Rambo"

list_liabilities shows all active commitments. Owners see all; Managers see only their assigned projects.

"How is Project Rambo performing financially?"

The monthly report and reporting sheet will show:

• Revenue: hours × billing_rate (normal)
• Cost: $5,000 (from the liability, not hours × hourly_cost)
• Margin: Revenue − $5,000

---

Cancelling a liability

If the engagement ends or the scope changes:

"Cancel liability #15"

The record is marked cancelled but kept in the audit trail. If you need a new amount, create a new liability.

---

P&L cost rule (summary)

For vendor X on project Y:

  Active liability exists?
  → YES: cost = liability.agreed_amount (fixed, ignores hours × rate)
  → NO:  cost = hours_logged × hourly_cost (standard hourly calculation)

The two methods are never blended for the same vendor/project pair.

---

Vendor vs. contractor

	Vendor	Contractor
employment_type	"vendor"	"contractor"
Cost method	Fixed fee (liability)	Hourly (Rate History)
Time logging	PM logs on their behalf	PM or self (if they have bot access)
Use case	Fixed-fee deliverables	Ongoing hourly work

Contractors follow the same rate-based cost calculation as FTE staff. If a contractor's cost should be a fixed fee, treat them as a vendor instead.