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

In the web console, open Users and add the person 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 won't message the bot themselves, and nobody records time for them: their hours and cost come from the liability.

---

Step 2: Create a liability

In the web console, open the project and add the liability from its Liabilities card — vendor, description, agreed amount and agreed hours.

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: There is no time to log

Nobody records time for a vendor (issue 2624). The liability carries their hours and cost: hours accrue evenly across the agreement's dates and count toward the project's burn, and the agreed amount is their cost.

---

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:

In the web console, cancel the liability from the project's Liabilities card, or from Liabilities in the left nav.

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	Nobody; the liability carries their hours	Self
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.