ADR-020: Enquiry Billing Model

Status: Draft Owner: @bilal Date: 2026-03-09

Context

The Acquisition commercial motion prices customers per enquiry. The current codebase has no concept of a billable enquiry — conversations exist but lack explicit resolution events, and text-based channels (WhatsApp, SMS, Chat) never close conversations. We need a precise, auditable, contractual definition of what constitutes a billable enquiry.

Decision

Adopt a hybrid approach: start with conversation-based billing mechanics, build toward explicit AI resolution signals.

Enquiry Definition

An enquiry is a single tenant interaction that reaches a meaningful outcome: issue created, question answered, or escalation to a human operator. Non-billable: abandoned conversations, spam, and failed identity verification.

Billing Categories

Category	Billable	Trigger
issue_created	Yes	Conversation created a maintenance issue
escalation	Yes	Conversation escalated to human operator
q_and_a	Yes	Conversation resolved without issue/escalation
abandoned	No	Tenant stopped responding before identity confirmed
spam	No	Detected as spam
identity_failed	No	Tenant could not be identified/confirmed

Auto-Resolution

Conversations auto-resolve after configurable inactivity timeout:

• Voice: Immediate (call-end webhook, already implemented)
• WhatsApp/SMS/Chat: 2 hours of no messages (configurable per org)

Phased Implementation

1. Phase 1 (Foundation): Add billable, billing_category, resolved_at columns to conversations. Implement auto-resolution background job.
2. Phase 2 (Acquisition MVP): Create enquiries table for aggregation and invoice line items.
3. Phase 3 (Future): Add resolve_conversation as an AI tool — explicit, intent-aware resolution rather than timeout-based.

Options Considered

Option	Pros	Cons
Conversation = Enquiry	Simple, every conversation = 1 billable unit	Spam/abandoned counted; customer disputes
Issue = Enquiry	Intuitive for customers	Under-counts (Q&A, escalations absorbed)
Hybrid (chosen)	Precise billing with categories; excludes non-billable	More implementation work; requires auto-resolution

Consequences

Easier:

• Clear contractual definition reduces billing disputes
• Non-billable categories (spam, abandoned) are fair to customers
• Phased approach delivers value incrementally

Harder:

• Auto-resolution timeout needs tuning per org/channel
• Multi-problem conversations (tenant reports 2 issues in 1 conversation) still count as 1 enquiry due to unique constraint on conversations.issue_id
• Dispute resolution process needs designing

Related

• ADR-019 Commercial Motions Architecture — parent architectural decision
• docs/05-Specs/Enquiry Billing Model.md — full analysis with edge cases and contractual wording
• envo-dashboard/lib/tenant-engine/conversation.ts — conversation CRUD
• docs/01-Architecture/Conversation Orchestration.md — current conversation lifecycle