Invoicing

Every milestone in an active project generates an invoice. The invoice workflow tracks the lifecycle of each payment from draft through approval to settlement, with structured paths for disputes and rejections.

Flow

Invoice Creation

The expert raises an invoice against a milestone (invoices are not auto-created on milestone completion). It inherits its financial values from the parent quote:

Field	Calculation	Description
`amount`	`quote.amount × (milestone.percentage / 100)`	Expert’s share for this milestone
`total`	`amount`	Total amount associated with this invoice

One invoice is created per milestone — enforced by a unique index on milestone. This means each milestone can only ever have one invoice, preventing duplicate billing.

Disputing an invoice also raises a delivery blocker on the engagement, so the dispute is visible in the team’s blocker queue until it is resolved (resolution returns the invoice to invoice_draft).

Invoice Status Workflow

Status	Transition Type	Meaning
`invoice_draft`	—	Raised by the expert against a milestone; awaiting manager approval
`invoice_sent`	`positive`	Approved by the manager; with the customer awaiting payment
`invoice_disputed`	`negative`	Manager has flagged an issue; loops back to draft after resolution
`invoice_paid`	`positive`	Payment confirmed; project value released
`invoice_rejected`	`negative`	Invoice rejected outright; terminal state

Payment Recording

When an invoice is marked as paid:

paid = true is set on the invoice record
paidAt is required and must be provided — the model validates that paidAt exists whenever paid is true
isApproved = true is set to indicate the full approval and payment cycle is complete

These flags are also surfaced as computed virtuals on the parent milestone (isPaid, isApproved), allowing milestone progress to be derived without joining the invoice collection.

Invoice Fields

Field	Type	Description
`quote`	Quote ref	The quote this invoice is billed against
`milestone`	Milestone ref	The completed milestone this invoice covers (unique)
`lead`	Lead ref	The originating lead
`expert`	User ref	The expert being paid
`customer`	User ref	The customer being billed
`manager`	User ref	The CSM managing the invoice
`vendor`	User ref	The vendor account
`amount`	Number	Expert payment for this milestone
`total`	Number	Total amount
`status`	String	Current invoice status name
`paid`	Boolean	Whether payment has been received
`paidAt`	Date	Required when `paid = true`
`dueDate`	Date	Optional payment due date; falls back to the linked milestone’s due date when unset

Notifications

Key invoice events trigger platform notifications to the relevant parties:

Event	Notification Key	Recipients
Invoice raised	`invoice-raised`	Manager, Customer
Invoice approved	`invoice-approved`	Expert
Invoice disputed	`invoice-disputed`	Expert
Invoice rejected	`invoice-rejected`	Expert
Payment confirmed	`invoice-paid`	Expert, Customer