Business logic & design

This page connects the strategy behind the Product Catalog to the systems that execute it. Use it when you need to translate commercial ideas into catalog configuration or when you must explain pricing logic to stakeholders.

Accessing the product catalog

The product catalog is available through the Products section in your Commet platform. From here you can:

• View all products: Browse your complete product portfolio with SKUs, descriptions, and tax categories
• Manage list prices: Create and edit standard prices for each product across currencies and segments
• Configure price variants: Set up customer-specific pricing with discounts, markups, or custom terms
• Link to agreements: See which agreements reference specific prices or variants

Why the catalog exists

The catalog solves pricing-complexity management for billing platforms that juggle multiple pricing models and customer-specific terms.

Problems it eliminates

• Custom code for every new price or promotion.
• Sales asking “What’s the official price?” vs. “What are we offering this customer?”
• Lack of analytics on discount adoption or premium pricing.
• No approval workflow for large enterprise concessions.
• Pricing updates blocked behind engineering queues.

Business outcomes

• Clear list price vs. customer price conversations.
• Accurate analytics for margins, discounts, and product performance.
• Negotiation playbooks that combine list tiers and approved variants.
• Automated governance that flags discounts beyond policy.
• Freedom to support any business model without code changes.

Four pricing layers working together

Prices act as the core building blocks in Commet. Each price defines unit cost, pricing model, currency, billing frequency, and billing type. These prices can be reused across multiple customers, making catalog management efficient and scalable.

Products describe the services you sell:
├── API Platform → API access with rate limiting
├── Analytics Dashboard → Reporting and insights
├── Premium Support → 24/7 help with SLA
├── Data Storage → Scalable storage
└── AI Processing → Machine learning services

Product: API Platform
├── List Price: Starter → $50/month, 10K calls included
├── List Price: Professional → $200/month, 100K calls included
├── List Price: Enterprise → $500/month, 1M calls included
└── List Price: Pay-per-use → $0.10 per call, no minimum

List Price: Enterprise ($500/month)
├── Price Variant: Acme Corp → 20% discount = $400/month
├── Price Variant: MercadoLibre → $500/month, 2M calls included
├── Price Variant: Startup Beta → 50% discount = $250/month
└── Price Variant: Enterprise Plus → 10% markup = $550/month

Agreement: Acme Corp – Q1 2025
├── Item 1: API Platform → Enterprise Plan (20% variant)
├── Item 2: Analytics Dashboard → Professional Plan (list price)
├── Item 3: Premium Support → Custom price variant
└── Contract discount: 5% promo for Q1

Each layer keeps analytics intact and separates permanent configuration (variants) from temporary negotiation tools (agreement discounts).

Price reusability and identification

Every price in the catalog has a unique price_id that serves as its identifier across the platform. This allows you to:

• Reuse standard prices across multiple customers without duplication
• Track pricing changes and maintain historical accuracy
• Reference prices consistently in agreements, invoices, and analytics
• Create variants from existing list prices while preserving the relationship

Real-world catalogs

Supported pricing models

Code-friendly examples live in the developer docs, but the catalog UI exposes each model as configurable options.

Governance rules

When to create a product

1. New value proposition or service line.
2. Different tax treatment.
3. Separate reporting needs.

When to publish a list price

1. New segment or market positioning.
2. Different commitment period or included units.
3. Switching pricing models (fixed vs. usage vs. tiers).

When to use a price variant

1. Customer-specific discount or currency.
2. Contracted unit changes or volume commitments.
3. Long-lived custom terms (not temporary promos).

When to apply agreement discounts

• Ramp-up phases, quarter promotions, or limited-time incentives.
• Layered on top of list prices and variants without breaking analytics.

Multi-tenant flexibility

Each organization running on Commet can configure its own catalog:

• Startup catalog: a single core product with 4 plans, a couple of add-ons, minimal variants.
• Enterprise catalog: multiple products, professional services, dozens of variants with approvals, aggressive discount policies.

The catalog supports both extremes on the same infrastructure, keeping segmentation, discount policies, and reporting separate.

Billing engine integration

All billing internals live in billing-engine.md, but here’s the high-level handshake:

• Products provide tax categories and descriptions for invoices.
• List prices act as the official baseline for negotiations.
• Price variants inject permanent customer customization.
• Pricing models (fixed, usage, seats, tiers) feed the billing calculator.
• Agreements combine everything and pass it downstream for invoice generation.

function resolveFinalPricing(agreementItem: AgreementItem) {
  const listPrice = getListPrice(agreementItem.listPriceId);
  let finalAmount = listPrice.unitAmount;

  if (agreementItem.priceVariantId) {
    const variant = getPriceVariant(agreementItem.priceVariantId);
    finalAmount = applyVariantPricing(finalAmount, variant);
  }

  if (agreementItem.agreementDiscountType) {
    finalAmount = applyAgreementDiscount(finalAmount, agreementItem);
  }

  return { listPrice, finalAmount };
}

Integration points with other modules

• Usage module: price_variant.usage_metric_id → usage_metric.id to track consumption.
• Seats module: agreement_item.quantity_source = 'seat_balance' pulls seat counts automatically.
• Tax module: product.tax_category_id → tax_category.id applies correct rates per product.
• Customer module: optional price_variant.customer_id to tie custom pricing to a specific account.

End-to-end workflow

1. Catalog setup: define the product portfolio and assign tax categories.
2. List price design: product marketing publishes official pricing for each segment.
3. Negotiation: sales crafts price variants with approvals for custom deals.
4. Contract signing: agreements reference list prices, variants, and temporary discounts.
5. Billing automation: the billing engine executes the cascade and produces transparent receipts.

Key success metrics

• Zero pricing errors in invoices.
• Full pricing-model coverage without engineering involvement.
• Sub-two-second pricing calculations even with complex tiers.
• No manual adjustments due to catalog limitations.

Troubleshooting common scenarios