coulomb/adaptive-pricing
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
31db9f8f3171d6b0ed8066f349481979bd814e38
adaptive-pricing/docs/ProductRequirementsDocument.md
tegwick 2e9675ccab Organize generic docs and Coulomb MVP project layout 
Move the framework PRD from specs/ to docs/ and remove the misplaced
specs/ directory. Document repository layout in AGENTS.md and SCOPE.md:
generic material in docs/, project-specific MVP artifacts in
projects/coulomb-pricing/, execution tracking in workplans/.
2026-06-22 01:07:39 +02:00

28 KiB
Raw Blame History

ProductRequirementsDocument.md

Adaptive Pricing

Version

0.1

Status

Draft

Repository

adaptive-pricing

1. Purpose

Adaptive Pricing is a pricing intelligence and execution platform for discovering, validating, optimizing, and operating pricing strategies across the full lifecycle of products, services, communities, platforms, and marketplaces.

The product supports pricing from the earliest inception of an idea through exploration, introduction, growth, maturity, saturation, and decline.

Adaptive Pricing treats pricing not as a static billing configuration, but as a lifecycle-spanning learning and control capability.

2. Product Thesis

Pricing is one of the most important mechanisms for discovering product-market fit.

A product team does not merely need to know:

What should we charge?

It needs to understand:

What value are we creating, for whom, under which conditions, at what cost, against which alternatives, with which risks, and through which commercial model?

Adaptive Pricing helps builders answer these questions systematically.

The product shall provide a practical framework for:

  • forming pricing hypotheses
  • understanding cost floors
  • exploring value ranges
  • analyzing market competition
  • selecting pricing models
  • designing pricing experiments
  • simulating economic outcomes
  • exposing safe pricing choices to customers
  • optimizing seller economics
  • translating pricing decisions into executable payment-provider configurations

The long-term ambition is to become an auto-regulating market value exploration pricing engine.

3. Problem Statement

Pricing decisions are often made too late, too statically, and with too little evidence.

Common problems include:

  • pricing is considered only after a product is already built
  • cost structures are poorly understood
  • willingness to pay is guessed rather than explored
  • customer value is not connected to price
  • competitive alternatives are not modeled explicitly
  • pricing experiments are informal and hard to compare
  • payment-provider configuration becomes hidden business logic
  • discounts are granted without understanding LTV impact
  • usage-based pricing is introduced without cost attribution
  • dynamic pricing damages trust when it is not explainable
  • pricing is not adapted to lifecycle stage
  • customer preferences are not used as pricing intelligence

Adaptive Pricing addresses these problems by making pricing hypotheses, models, observations, simulations, constraints, and executions explicit.

4. Unique Value Proposition

Adaptive Pricing supports pricing throughout the complete product lifecycle, beginning before the product exists.

Unlike billing systems, payment providers, subscription managers, or revenue platforms, Adaptive Pricing is not primarily concerned with invoice execution.

Its core value is to help teams discover and operate economically valid pricing models.

Adaptive Pricing combines:

  1. Pricing intelligence Understanding value, cost, competition, risk, customer behavior, and lifecycle stage.

  2. Pricing model design Defining reusable, composable, testable pricing models.

  3. Pricing experimentation Structuring and evaluating evidence about willingness to pay and value perception.

  4. Pricing simulation Comparing pricing alternatives before activation.

  5. Customer-tunable pricing Allowing customers to adjust pricing trade-offs while preserving seller economics.

  6. Pricing execution Translating validated pricing models into payment-provider artifacts.

  7. Pricing governance Keeping pricing decisions explainable, auditable, bounded, and lifecycle-aware.

5. Core Concept

The core object of Adaptive Pricing is not the price.

The core object is the Pricing Hypothesis.

A Pricing Hypothesis captures a belief about value, willingness to pay, cost, risk, customer behavior, competition, or pricing mechanics.

Examples:

  • Customers will pay a monthly subscription for access to a community and its knowledge assets.
  • Usage-based AI functionality should be priced based on actual provider cost plus a working margin.
  • Customers prefer predictable monthly cost over low base price with volatile overage.
  • Annual commitment justifies a lower unit price.
  • Volume discounts are only economically valid when tied to minimum turnover commitments.
  • Enterprise customers value support, compliance, and SLA more than raw usage volume.
  • A product in exploration should optimize for learning, while a mature product should optimize for margin and retention.

Adaptive Pricing helps validate, refine, reject, and operationalize such hypotheses.

6. Lifecycle Model

Adaptive Pricing shall support pricing work across the following lifecycle phases.

6.1 Idea

The product does not yet exist.

Primary questions:

  • Who might receive value?
  • What pain or desire is addressed?
  • What alternatives already exist?
  • How expensive is the problem?
  • What pricing patterns might fit?
  • Which willingness-to-pay assumptions should be tested?

Supported capabilities:

  • value hypothesis capture
  • customer segment assumptions
  • alternative and competition mapping
  • early pricing pattern suggestions
  • research task generation
  • initial value-range estimation

6.2 Exploration

The product concept, prototype, or early offer is being tested.

Primary questions:

  • Will anyone pay?
  • What will they pay for?
  • Which value metric seems plausible?
  • Which pricing model creates the least friction?
  • What must be learned before scaling?

Supported capabilities:

  • pricing experiments
  • pilot pricing
  • customer interview capture
  • willingness-to-pay research
  • cost floor estimation
  • value metric exploration
  • early pricing model comparison

6.3 Introduction

The product enters the market with first paying customers.

Primary questions:

  • Which pricing model converts?
  • Which customer segments respond?
  • Which costs matter?
  • Which pricing promises must be stable?
  • What price communication works?

Supported capabilities:

  • launch pricing models
  • early revenue analysis
  • adoption-friction detection
  • introductory offers
  • pricing-page variant comparison
  • basic customer segmentation
  • early margin analysis

6.4 Growth

Customer base and usage expand.

Primary questions:

  • Which segments are most valuable?
  • Which customers expand?
  • Which pricing model scales?
  • Which usage metrics correlate with value?
  • Which packages increase adoption and revenue?

Supported capabilities:

  • segmentation analysis
  • expansion revenue analysis
  • usage-based pricing analysis
  • packaging optimization
  • pricing model simulation
  • LTV comparison
  • churn and retention analysis
  • commitment and discount evaluation

6.5 Maturity

The product has stable demand and known customer segments.

Primary questions:

  • How should margin be optimized?
  • How should plans be packaged?
  • Which customers are underpriced or overpriced?
  • Which discounts are economically justified?
  • Which pricing model best supports retention?

Supported capabilities:

  • margin optimization
  • plan consolidation
  • customer-level profitability analysis
  • pricing governance
  • discount policy modeling
  • renewal pricing
  • portfolio pricing
  • dynamic recommendation

6.6 Saturation

Growth slows and competition increases.

Primary questions:

  • How can market position be defended?
  • Which bundles improve retention?
  • Which segments remain attractive?
  • Which price changes create risk?
  • Which offers should be simplified?

Supported capabilities:

  • competitive repricing analysis
  • bundle evaluation
  • retention pricing
  • churn-risk pricing analysis
  • portfolio comparison
  • migration offers
  • customer cohort analysis

6.7 Decline

The product is being harvested, replaced, migrated, or retired.

Primary questions:

  • Should the product be maintained, migrated, harvested, or sunset?
  • Which customers should be moved to another offer?
  • Which price supports long-tail maintenance?
  • Which commitments should no longer be accepted?

Supported capabilities:

  • sunset pricing
  • migration pricing
  • long-tail profitability analysis
  • contract risk analysis
  • simplified maintenance pricing
  • customer transition offers

7. Product Scope

Adaptive Pricing shall provide a practical product framework for pricing intelligence, pricing model design, simulation, recommendation, and execution.

7.1 In Scope

Adaptive Pricing shall support:

  • pricing hypothesis management
  • pricing model definition
  • pricing lifecycle modeling
  • cost floor analysis
  • value range exploration
  • market competition analysis
  • pricing experiment design
  • customer segment analysis
  • usage and cost attribution
  • LTV modeling
  • pricing simulation
  • pricing recommendation
  • customer-tunable pricing
  • constraint evaluation
  • payment-provider synchronization
  • audit and explanation of pricing decisions

7.2 Out of Scope

Adaptive Pricing shall not become:

  • only a billing system
  • only a Stripe wrapper
  • only a pricing research document collection
  • only a dashboard
  • only a dynamic pricing tool
  • only a discount calculator
  • only a SaaS subscription manager

Billing providers remain execution backends.

Adaptive Pricing owns the pricing intelligence, pricing model, constraints, and lifecycle logic.

8. Target Users

8.1 Primary Users

  • founders
  • builders
  • product owners
  • SaaS operators
  • platform operators
  • marketplace operators
  • community operators
  • pricing strategists
  • revenue operators
  • customer success teams
  • sales teams
  • AI agents assisting with product and pricing decisions

8.2 Secondary Users

  • finance teams
  • business analysts
  • growth teams
  • product marketers
  • investors
  • procurement advisors
  • implementation partners

9. Key User Needs

Users need to:

  • reason about pricing before the product is finished
  • make pricing assumptions explicit
  • compare alternative pricing models
  • understand cost floors
  • estimate value ranges
  • evaluate market alternatives
  • choose value metrics
  • identify economically valid discounts
  • avoid accidental margin destruction
  • expose pricing flexibility safely
  • understand customer trade-offs
  • operationalize pricing decisions without manual provider setup
  • explain pricing recommendations to stakeholders

10. Core Product Capabilities

10.1 Pricing Hypothesis Management

The system shall allow users to capture, structure, evaluate, and refine pricing hypotheses.

A pricing hypothesis may relate to:

  • customer segment
  • value proposition
  • willingness to pay
  • cost structure
  • competition
  • lifecycle phase
  • pricing model
  • commitment level
  • discount rule
  • usage metric
  • outcome metric
  • payment terms
  • customer preference

Each hypothesis should have:

  • statement
  • rationale
  • affected offering
  • lifecycle phase
  • confidence level
  • evidence
  • related experiments
  • status
  • decision history

10.2 CostFloor Modeling

The system shall help users understand the minimum economically viable pricing boundary.

CostFloor shall consider:

  • fixed costs
  • variable costs
  • payment-provider fees
  • support cost
  • onboarding cost
  • infrastructure cost
  • third-party API cost
  • human effort
  • working capital
  • risk buffer
  • target minimum margin

CostFloor shall not be treated as the final price.

It is a lower economic boundary.

10.3 ValueRange Exploration

The system shall help users estimate and refine the range of prices that may be justified by customer value.

ValueRange may be informed by:

  • customer interviews
  • willingness-to-pay research
  • observed usage
  • customer outcomes
  • saved cost
  • generated revenue
  • reduced risk
  • time saved
  • emotional value
  • community value
  • switching cost
  • strategic importance

10.4 MarketCompetition Modeling

The system shall help users compare an offering against alternatives.

Alternatives may include:

  • direct competitors
  • indirect competitors
  • manual workarounds
  • internal build options
  • open-source alternatives
  • agency or consulting substitutes
  • doing nothing
  • existing customer workflows

MarketCompetition should influence pricing strategy but not mechanically determine price.

10.5 Pricing Model Definition

The system shall allow users to define pricing models from reusable primitives.

Supported primitives should include:

  • fixed fee
  • subscription
  • one-time fee
  • setup fee
  • usage meter
  • included usage
  • overage
  • credits
  • prepaid packages
  • volume tiers
  • graduated tiers
  • stairstep tiers
  • minimum commitment
  • annual commitment
  • contract duration
  • discount
  • rebate
  • bundle
  • feature package
  • support package
  • SLA package
  • outcome fee
  • success fee
  • cancellation flexibility
  • payment term adjustment

10.6 Customer-Tunable Pricing

The system shall allow sellers to expose selected pricing parameters as customer-tunable.

Customer tuning may include preferences such as:

  • lower monthly base price
  • higher included usage
  • lower usage price
  • stronger budget predictability
  • higher flexibility
  • lower upfront payment
  • lower long-term cost
  • higher support level
  • shorter contract
  • longer commitment
  • prepaid usage
  • volume discount

Customer tuning shall not produce arbitrary discounts.

When a customer changes tunable parameters, the system shall solve remaining non-fixed parameters so that seller economics remain valid.

A tuned model shall be valid only if it satisfies seller-defined constraints.

10.7 Comparable Customer LTV Evaluation

The system shall support a seller-side metric tentatively named:

average_comparable_customer_lifetime_value

This metric estimates expected lifetime value for a customer under a given pricing configuration compared with similar customers, segments, usage expectations, risk profiles, and contract conditions.

Customer-tuned pricing configurations shall be evaluated against a reference model:

most_favorable_predefined_model

A customer-tuned model should only be valid if:

average_comparable_customer_lifetime_value(tuned_model)
>= average_comparable_customer_lifetime_value(most_favorable_predefined_model)
   × required_improvement_factor

The required improvement factor shall be configurable by the seller.

10.8 Boundary Condition Evaluation

The system shall evaluate pricing configurations against explicit boundary conditions.

Boundary conditions may include:

  • cost floor
  • minimum margin
  • minimum turnover
  • minimum commitment
  • payment-provider fees
  • expected usage variance
  • support effort
  • onboarding effort
  • contract duration
  • churn risk
  • default risk
  • upfront investment risk
  • capital lockup
  • operational capacity
  • service-level risk
  • abuse risk
  • compliance constraints
  • tax constraints
  • accounting constraints
  • customer segment eligibility
  • sales approval thresholds
  • maximum discount exposure

Boundary conditions shall be inspectable, testable, and explainable.

10.9 Pricing Simulation

The system shall allow users to simulate pricing models before execution.

Simulations should support:

  • expected revenue
  • expected cost
  • gross margin
  • contribution margin
  • cost per customer
  • revenue per customer
  • LTV
  • churn sensitivity
  • usage sensitivity
  • payment fee sensitivity
  • customer segment mix
  • adoption assumptions
  • risk scenarios
  • discount exposure
  • capacity pressure

Simulation results shall be comparable across pricing models.

10.10 Recommendation Engine

The system shall generate pricing recommendations based on observed data, hypotheses, lifecycle stage, constraints, and simulations.

Recommendations may include:

  • increase price
  • decrease price
  • change pricing model
  • introduce usage-based component
  • introduce minimum commitment
  • reduce discount
  • add plan tier
  • remove plan tier
  • introduce annual commitment
  • add credit package
  • add overage
  • change included usage
  • segment customers differently
  • run pricing experiment
  • collect more evidence before changing price

Recommendations shall include rationale, confidence, risks, and supporting evidence.

10.11 Pricing Execution

The system shall translate validated pricing models into payment-provider artifacts.

Payment providers may include:

  • Stripe
  • Paddle
  • Chargebee
  • Lago
  • Orb
  • m3ter
  • custom billing systems

For Stripe, the system should eventually support automated management of:

  • products
  • prices
  • recurring subscriptions
  • metered usage prices
  • usage records
  • tiers
  • coupons
  • discounts
  • subscription configurations
  • invoices
  • billing periods
  • tax-relevant metadata
  • product metadata
  • lifecycle states

The Adaptive Pricing model shall remain the source of truth.

Payment-provider state shall be generated, synchronized, reconciled, and audited.

11. Functional Requirements

11.1 Pricing Knowledge

FR-001

The system shall maintain a registry of pricing hypotheses.

FR-002

The system shall maintain a registry of offerings.

FR-003

The system shall maintain a registry of customer segments.

FR-004

The system shall maintain a registry of pricing models.

FR-005

The system shall maintain a registry of pricing experiments.

FR-006

The system shall maintain a registry of pricing observations.

11.2 Lifecycle Support

FR-010

The system shall assign lifecycle phases to offerings.

FR-011

The system shall recommend pricing activities based on lifecycle phase.

FR-012

The system shall allow lifecycle phase transitions to be recorded.

FR-013

The system shall preserve pricing history across lifecycle phases.

11.3 Cost, Value, and Competition

FR-020

The system shall model fixed costs.

FR-021

The system shall model variable costs.

FR-022

The system shall model payment-provider fees.

FR-023

The system shall calculate CostFloor.

FR-024

The system shall capture ValueRange assumptions.

FR-025

The system shall capture MarketCompetition assumptions.

FR-026

The system shall associate evidence with cost, value, and competition assumptions.

11.4 Pricing Models

FR-030

The system shall define pricing models using composable primitives.

FR-031

The system shall distinguish fixed, seller-controlled, customer-tunable, calculated, and constrained parameters.

FR-032

The system shall version pricing models.

FR-033

The system shall compare pricing model versions.

FR-034

The system shall mark pricing models as draft, experimental, active, deprecated, or retired.

11.5 Customer-Tunable Pricing

FR-040

The system shall allow sellers to expose selected parameters for customer tuning.

FR-041

The system shall calculate dependent parameters when customer-tunable parameters change.

FR-042

The system shall reject tuned configurations that violate seller constraints.

FR-043

The system shall explain why a tuned configuration is valid or invalid.

FR-044

The system shall compare tuned configurations with predefined reference models.

11.6 LTV and Economic Evaluation

FR-050

The system shall calculate expected revenue for a pricing model.

FR-051

The system shall calculate expected cost for a pricing model.

FR-052

The system shall calculate expected margin for a pricing model.

FR-053

The system shall estimate customer lifetime value.

FR-054

The system shall support average comparable customer LTV calculations.

FR-055

The system shall support configurable required improvement factors.

11.7 Boundary Conditions

FR-060

The system shall define boundary conditions.

FR-061

The system shall evaluate pricing configurations against boundary conditions.

FR-062

The system shall explain boundary condition violations.

FR-063

The system shall support approval thresholds for risky configurations.

11.8 Simulation

FR-070

The system shall simulate pricing models under configurable assumptions.

FR-071

The system shall compare multiple pricing scenarios.

FR-072

The system shall simulate customer segment mixes.

FR-073

The system shall simulate usage variance.

FR-074

The system shall simulate discount exposure.

FR-075

The system shall simulate lifecycle-specific strategies.

11.9 Recommendations

FR-080

The system shall generate pricing recommendations.

FR-081

Recommendations shall include rationale.

FR-082

Recommendations shall include confidence.

FR-083

Recommendations shall include risks.

FR-084

Recommendations shall reference supporting observations.

FR-085

Recommendations shall distinguish between suggested research, suggested simulation, suggested model change, and suggested execution.

11.10 Execution Integrations

FR-090

The system shall maintain payment-provider-independent pricing definitions.

FR-091

The system shall map internal pricing models to payment-provider artifacts.

FR-092

The system shall synchronize active pricing models with payment providers.

FR-093

The system shall detect drift between internal model state and provider state.

FR-094

The system shall maintain an audit trail of pricing execution.

12. Non-Functional Requirements

12.1 Explainability

All recommendations, simulations, validations, and rejections shall be explainable.

12.2 Auditability

Pricing decisions and changes shall be reproducible from recorded data, assumptions, and model versions.

12.3 Provider Independence

Pricing models shall not depend structurally on a single payment provider.

12.4 Extensibility

New pricing primitives, constraints, integrations, and lifecycle playbooks shall be addable without redesigning the core model.

12.5 Trust Preservation

Adaptive pricing shall avoid hidden exploitation. Customer-facing adaptive pricing should be understandable, bounded, and based on explicit trade-offs.

12.6 Regulatory Awareness

The system shall support governance and audit features needed for fair, explainable, and compliant pricing practices.

12.7 Agent Readiness

The system shall be usable by both humans and AI agents. Important concepts, assumptions, and decisions shall be represented in structured, machine-readable form.

13. Conceptual Data Model

Offering

Represents a product, service, community, marketplace, platform, or bundle that may be priced.

Pricing Hypothesis

Represents a testable belief about value, cost, competition, customer behavior, or pricing mechanics.

Pricing Model

Represents a structured commercial model composed of pricing primitives.

Pricing Primitive

Represents an atomic pricing component such as subscription, usage meter, discount, commitment, or outcome fee.

Pricing Parameter

Represents a configurable value inside a pricing model.

Boundary Condition

Represents an economic, operational, legal, or strategic constraint.

Pricing Experiment

Represents a structured attempt to validate or falsify pricing hypotheses.

Pricing Observation

Represents evidence collected from customers, usage, revenue, interviews, market research, or experiments.

Customer Segment

Represents a group of customers with similar needs, economics, risk, usage, or willingness to pay.

Pricing Scenario

Represents a simulated pricing configuration under explicit assumptions.

Pricing Recommendation

Represents a suggested action based on evidence, simulation, lifecycle state, and constraints.

Payment Execution Mapping

Represents the translation from internal pricing model to payment-provider artifacts.

14. Pricing Governance

Adaptive Pricing shall support governance for pricing changes.

Governance capabilities should include:

  • model versioning
  • approval workflows
  • discount policies
  • customer communication requirements
  • grandfathering rules
  • lifecycle-state rules
  • risk thresholds
  • provider synchronization logs
  • audit history
  • rollback support

Pricing changes should not be treated as casual configuration edits.

They are product, business, customer, and trust decisions.

15. Success Metrics

Adaptive Pricing is successful if users can:

  • capture pricing assumptions early
  • convert assumptions into pricing hypotheses
  • design experiments to validate willingness to pay
  • understand cost floors
  • estimate value ranges
  • compare market alternatives
  • define pricing models structurally
  • simulate economic outcomes
  • expose safe customer pricing choices
  • preserve seller economics under customer tuning
  • identify invalid discounts
  • generate explainable pricing recommendations
  • execute pricing models through payment providers
  • keep pricing models auditable and lifecycle-aware

Business success may be measured by:

  • improved pricing confidence
  • reduced manual pricing work
  • fewer invalid discounts
  • better margin visibility
  • better lifecycle fit of pricing models
  • improved customer conversion
  • improved retention
  • improved average comparable customer LTV
  • faster pricing experiment cycles
  • lower payment-provider configuration errors

16. Product Boundaries

Adaptive Pricing should integrate with payment providers, analytics systems, CRM systems, product usage systems, and financial tools.

However, it should not become a replacement for all of them.

The product’s durable center is:

pricing knowledge, pricing reasoning, pricing simulation, pricing governance, and pricing execution mapping.

17. Development Horizons

Horizon 1 — Pricing Knowledge Foundation

Establish the core model:

  • offering
  • lifecycle phase
  • pricing hypothesis
  • cost floor
  • value range
  • market competition
  • pricing model
  • pricing primitive
  • pricing observation

Horizon 2 — Simulation and Recommendation

Add:

  • pricing scenarios
  • lifecycle-aware playbooks
  • economic simulation
  • recommendation logic
  • risk and constraint explanation

Horizon 3 — Customer-Tunable Pricing

Add:

  • tunable parameter surfaces
  • constraint solving
  • comparable customer LTV comparison
  • safe customer preference trade-offs

Horizon 4 — Execution Automation

Add:

  • Stripe integration
  • additional payment-provider integrations
  • provider drift detection
  • automated price creation
  • subscription and usage billing synchronization

Horizon 5 — Auto-Regulating Pricing

Add:

  • continuous market value exploration
  • automated recommendation loops
  • bounded adaptive pricing
  • pricing health monitoring
  • lifecycle-aware auto-regulation
  • trust-preserving dynamic pricing

18. Strategic Positioning

Adaptive Pricing should become the pricing capability layer for offerings built on this framework and related product ecosystems.

It should also be useful as a standalone product for builders, founders, SaaS teams, platform operators, marketplace creators, and AI-assisted business development workflows.

The product should occupy the space between:

  • pricing research
  • product strategy
  • revenue operations
  • billing infrastructure
  • customer preference modeling
  • economic simulation
  • payment-provider automation

Its defining claim:

Adaptive Pricing helps builders discover, validate, optimize, and execute pricing models from the first idea to the final lifecycle stage.

19. Open Questions

The following questions require further research and refinement:

  • How should ValueRange be estimated before customer data exists?
  • Which pricing experiment formats should be supported first?
  • How should average comparable customer LTV be defined precisely?
  • Which pricing primitives should be considered canonical?
  • How should customer-tunable pricing be presented without confusing customers?
  • Which fairness rules should constrain adaptive pricing?
  • How should lifecycle phase transitions be detected?
  • How should payment-provider drift be reconciled?
  • How should pricing recommendations be validated before execution?
  • Which pricing decisions should require human approval?
  • How should AI agents participate in pricing exploration safely?

20. Summary

Adaptive Pricing is a lifecycle-spanning pricing intelligence and execution platform.

It helps builders reason from early pricing hypotheses to executable pricing models. It supports cost floor analysis, value range exploration, market competition modeling, pricing experiments, simulations, recommendations, customer-tunable pricing, and payment-provider execution.

The product is not merely about automating billing.

It is about making pricing an explicit, adaptive, evidence-based, and trustworthy product capability.

Reference in New Issue View Git Blame Copy Permalink