CPQ: Configure · Price · Quote

What is CPQ?#

CPQ stands for Configure · Price · Quote. It is the industry-standard sales motion for enterprise B2B deals where pricing is negotiated, contracts require legal review, and procurement teams demand a formal quote document before signing.

Without CPQ, sales-led deals collapse into ad-hoc spreadsheets, manually drafted PDFs, and out-of-band approval emails. The result: pricing leaks, missed approvals, and post-deal provisioning drift. CPQ replaces that chaos with one workflow: the sales rep configures the deal (which offering, which rate plan, which discount), the system prices it (mathematically, against locked rate plan versions), and a formal quote is generated for approval and signature.

How Aforo Provides CPQ#

Aforo's CPQ ships as a first-class feature inside Pricing Studio. There is no separate CPQ product to license, no third-party integration to configure, no Salesforce CPQ data sync to maintain. CPQ lives alongside your rate plans, offerings, and subscriptions — because quotes reference all three and convert into the fourth atomically.

The architecture mirrors what Zuora, Chargebee, and Salesforce CPQ do for the largest SaaS companies — but co-located in your billing platform so there is no data-sync lag, no out-of-band reconciliation, and no separate audit trail. Approvals, acceptance, PDF generation, and conversion all share the same workspace context, the same access controls, and the same audit trail as the rest of Aforo.

Quote Lifecycle (8-State Machine)#

Every quote moves through a deterministic state machine. Transitions are enforced server-side — invalid transitions are rejected immediately, and repeating a transition you've already made (for example, submitting the same draft for approval twice) is a safe no-op.

DRAFT ──submitForApproval──▶ IN_REVIEW ──approve──▶ APPROVED ──send──▶ SENT
DRAFT ──send (when no approval rule matches)───────────────────────▶ SENT
IN_REVIEW ──reject──▶ REJECTED (terminal)
SENT ──accept (customer)──▶ ACCEPTED ──convertToSubscription──▶ CONVERTED (terminal)
SENT ──reject (customer)──▶ REJECTED (terminal)
SENT ──expire (hourly scheduler, past valid_until)──▶ EXPIRED (terminal)

State Definitions#

Quote Builder Wizard (5 Steps)#

Sales reps build quotes through a 5-step wizard at /cpq/new. The wizard preserves field state on Back, validates each step before allowing Next, and shows a sticky ACV sidebar on the right that recomputes as the term, discount, and usage estimates change.

Usage on a Quote#

A rate card can charge a base fee, usage, or both. A quote carries one line per priced part: the recurring base fee and one usage line per billable unit. A usage line states the unit's pricing terms in words, for every pricing model: the per-unit rate, every tier or price band, the included quantity, block size, minimum fee, percentage, and for outcome-based pricing the weight of each outcome (for example SUCCESS 1 · HITL_REQUIRED 0). The same lines appear in the builder, the detail drawer, the PDF, and the customer acceptance page.

Usage has no fixed price until it happens, so a quote keeps three figures apart:

Estimates are optional. A usage line with no estimate reads Not estimated and adds nothing to the total, so the total can no longer be judged against an ACV threshold. To submit such a quote the rep must either enter an expected quantity or tick Send without a usage estimate, and the quote then always goes to an approver. See Approval Rules Engine.

Quote Fields Reference#

Each quote carries the following fields.

Identity & Workspace Fields#

Customer Fields (Dual-Mode)#

A quote is built for either an existing customer or a prospect — never both. When a prospect quote is accepted and converted, Aforo automatically creates a customer record for them — idempotent, so a retried conversion never produces a duplicate.

Offering & Rate Plan Fields#

Pricing Fields (NUMERIC 22,8 precision)#

Terms Fields#

Acceptance & Audit Fields#

Conversion Output Fields#

Audit Timestamps#

Every quote carries created_at, updated_at, submitted_at, approved_at, sent_at, rejected_at, expired_at, and converted_at — all TIMESTAMPTZ, populated by the state machine on transition.

Line Item Fields#

Each quote has one or more line items. Deleting a DRAFT quote removes its line items automatically.

Approval Rules Engine#

When a quote is submitted for approval, Aforo evaluates all configured rules for your workspace and selects the first matching rule, ordered by threshold (lowest threshold wins). The matched rule's required approver role becomes the tier the quote routes to.

Rule Types (v1)#

Rule Fields#

Approval Records#

When the engine routes a quote to an approver tier, a quote_approvals row is created with decided_at = NULL. The pending-queue UI scans the partial index idx_quote_approvals_pending WHERE decided_at IS NULL for the hot path.

Customer Acceptance Flow#

After internal approval, the sales rep clicks Send to Customer. This (a) mints a 32-byte cryptographic acceptance token, (b) constructs a customer-facing URL https://<tenant-storefront>/quote/<token>, (c) emails it to the customer (or copies it to clipboard for manual delivery), and (d) transitions the quote to SENT.

Public Route (No Auth Required)#

The token IS the bearer. There is no JWT, no login, no SSO. The customer clicks the link, lands on QuoteAcceptPage in the storefront-ui, and sees the quote with your workspace's branding (logo, legal name, address from billing_entity).

Click-Through Acceptance Doctrine#

v1 ships with click-through acceptance — legally binding under U.S. case law (Specht v. Netscape, ProCD v. Zeidenberg) and equivalent EU + APAC jurisdictions. On Accept, the server captures:

• Timestamp — accepted_at (server clock, TIMESTAMPTZ)
• IP address — accepted_ip (INET; X-Forwarded-For respected behind ALB)
• User agent — accepted_user_agent (TEXT; full UA string for forensics)
• Token — the cryptographic token itself (proof the customer received the email)

Brute-Force Defense#

The public route is protected by Kong route route-pricing-public-quotes with per-IP rate limit 10 requests/min. All error paths (token expired, status closed, cross-workspace probe) return HTTP 404 — same shape as not-found — so attackers cannot enumerate token validity by comparing differential error responses.

Quote → Subscription Conversion#

When the customer accepts, Aforo converts the quote into a live subscription as one atomic operation. If any step fails, the whole conversion rolls back and the quote stays ACCEPTED so it can be safely retried. Converting an already-converted quote is a no-op that returns the existing subscription.

Conversion Steps (in order)#

CPQ Inbox + Browse Page#

The merged CPQ page at /cpq replaces the prior split between Quotes and Approval Queue. It combines an inbox-style attention strip for approvers with a full browse-and-filter quote table for everyone.

Page Anatomy#

Quote Detail Drawer (5 Tabs)#

Clicking any quote row opens a slide-in drawer with 5 tabs. Action buttons in the drawer header are state-aware — they appear only when the state machine allows that transition.

State-Aware Drawer Actions#

Roles & RBAC#

Two CPQ-specific composite Keycloak roles ship in realm-aforo-prod.json. Both compose MEMBER for baseline platform access.

v1 Scope & v2 Roadmap#

v1 ships the core flow: configure → price → quote → internal approval → customer acceptance → auto-conversion. Each deferred item below becomes its own follow-up prompt when an enterprise customer asks.

Cross-Links#

CPQ depends on the broader Aforo monetization fabric. Quotes reference rate plan versions, offerings, and billing entities; conversions produce subscriptions that flow into the billing engine.