SuperAPI AI Directory

13-saas-billing-and-metering-spec

General & other

View repository

Updated 10-16 03:40

About this skill

SaaS Billing & Metering Spec Skill

Use When

  • specifying SaaS usage events, billing, credits, refunds, dunning, finance handoff, and testable metering controls; use pricing-and-packaging for commercial tier design.
  • Use this procedure when the required source artefacts are available and SaaS billing and metering specification is the next lifecycle deliverable.

Do Not Use When

  • Use pricing-and-packaging when that neighbouring route owns the decision or deliverable.
  • Do not invent missing project evidence, standards clauses, thresholds, or stakeholder decisions.

Required Inputs

Artefact Source or provider Required? Behaviour when missing
Approved pricing, entitlement, finance, and tenant context Product owner and finance doctrine Yes Stop the affected step, name the missing source, and return only a qualified gap record.

Workflow

  1. Inspect the required inputs and log the exact sources, versions, and unresolved assumptions.
  2. Apply this skill's existing domain workflow and decision rules to produce SaaS billing and metering specification.
  3. Stop when a required source, accountable decision owner, or deterministic test oracle is absent.
  4. Recover by preserving valid work, marking the blocked scope, and returning the narrowest qualified artefact plus the next evidence needed.

Outputs

Artefact Consumer Acceptance condition
SaaS billing and metering specification Architecture, finance, API, and test owners Required sections are populated, source links resolve, and every material requirement or decision has an observable review or test oracle.

Evidence Produced

Evidence Reviewer Acceptance condition
Source, decision, trace, and validation record for SaaS billing and metering specification Requirements quality reviewer Inputs used, decisions made, checks run, failures, and unassessed items are explicit.

Capability and permission boundaries

Read and search are required. Editing is allowed only when the request authorises creation or repair of the named requirements artefact. Publishing, production mutation, destructive action, spending, and certification require explicit authority.

Degraded mode

Fallback: if a required file, reviewer, standard source, network check, renderer, or execution capability is unavailable, return the narrowest useful qualified result and mark the affected check not assessed; never convert an unassessed check into a pass.

Decision Rules

Choice or condition Action Failure or risk avoided
A chargeable event cannot be tied to tenant, source, quantity, and idempotency key Reject the event contract and close the lineage gap. Unbillable usage, duplicate charges, or unauditable revenue.
Required inputs and test oracles are complete Continue through the existing workflow and record evidence. A deliverable whose acceptance cannot be reproduced.
A mandatory source or owner is missing Stop the affected branch and issue a qualified gap record. Fabricated context or unauthorised decisions.

Quality Standards

  • Preserve stable identifiers and bidirectional traceability from project evidence to SaaS billing and metering specification and its acceptance checks.
  • Apply ISO/IEEE measures only with a named metric, method, threshold, evidence source, and responsible reviewer; run the anti-slop gate before release.

Anti-Patterns

  • Producing SaaS billing and metering specification from assumed context. Fix: cite the project source or mark the scope blocked.
  • Accepting a material requirement without a deterministic oracle. Fix: add a measurable result, boundary, and verification method.
  • Crossing into pricing-and-packaging without routing the decision. Fix: hand off the named input and preserve trace links.
  • Treating an unavailable check as passed. Fix: mark it not assessed and state the release consequence.
  • Claiming standards, statutory, or stakeholder approval without evidence. Fix: cite the source and reviewer or qualify the claim.

References

Overview

Generates the requirements specification for the SaaS billing-and-metering pipeline. Sourced from Mersch (financial-metrics rigor) and Golding (control-plane responsibilities).

Core Instructions

Step 1: Inventory metered events

For every billable or quota-limited action, produce a row:

Event name Schema Granularity Source service Sink Retention raw / aggregate Used for Tenant fields
api.request.completed {tenant_id, endpoint, ts, status, bytes_in, bytes_out, duration_ms} per request Gateway metering bus 13 mo / 7 y rate limit + per-call pricing + analytics tenant_id, tier
storage.snapshot {tenant_id, bytes_used, ts} hourly Storage service metering bus 13 mo / 7 y GB-hour pricing tenant_id, tier
seat.assigned {tenant_id, user_id, ts, role} per change Identity metering bus 13 mo / 7 y per-seat pricing tenant_id
feature.used {tenant_id, feature_id, ts} per use App services metering bus 13 mo / 7 y tier enforcement + analytics tenant_id, tier

Step 2: Tenant-context propagation rules

Every event MUST include tenant_id. Every billable event MUST also include tier, region, and source trace_id. Events missing tenant_id MUST be rejected at the bus ingress and logged.

Step 3: Transport, ordering, retention

  • Transport: append-only event bus (Kafka / Kinesis / SQS-FIFO).
  • Ordering: per-tenant partition key.
  • Delivery: at-least-once with idempotency keys.
  • Retention raw: 13 months (audit-able billing dispute window).
  • Retention aggregates: 7 years (SOX / financial-records).

Step 4: Aggregation & pricing engine

  • Rollups: minute → hour → day → month per tenant per meter.
  • Pricing engine: consumes aggregates + tier price book + contract overrides → produces invoice line items.
  • Tier price book is versioned; price changes require a versioned price book and an ADR.

Step 5: Revenue-recognition rules (ASC 606 / IFRS 15)

  • Identify the contract.
  • Identify performance obligations (subscription, professional services, usage overages).
  • Determine transaction price.
  • Allocate to performance obligations.
  • Recognise revenue as obligations satisfied (typically subscription ratable, services on milestone, usage on consumption).

Document for each price-list line: revenue-recognition pattern (ratable / point-in-time / milestone / usage).

Step 6: Dunning, refunds, credits

  • Dunning sequence: D+0 reminder, D+3 first warning, D+7 second warning + read-only flag, D+14 suspension, D+45 offboarding.
  • Refunds: who can issue, dollar thresholds, audit, ERP entry.
  • Credits (service-credit from SLA breach): how applied, expiration, ERP entry.

Step 7: Audit & reconciliation

  • Daily reconciliation: metering aggregate vs gateway raw count vs charged amount.
  • Discrepancy alarm threshold: 0.1%.
  • Annual external audit (for series-B+ companies).

Step 8: ERP / finance handoff

  • Export cadence (daily journals).
  • Format (CSV / API / Avro).
  • Mapping: meter → GL account → cost centre.
  • Period-end close cutoff rules.

Step 9: Write the spec

Billing_And_Metering_Spec.md with sections: 1) Metered Event Catalogue, 2) Tenant Context Rules, 3) Transport / Retention / Ordering, 4) Aggregation & Pricing Engine, 5) Revenue Recognition (ASC 606 / IFRS 15), 6) Dunning / Refunds / Credits, 7) Audit & Reconciliation, 8) ERP Handoff, 9) Traceability to PRD pricing and SRS NFRs.

Standards

  • ASC 606 / IFRS 15 — Revenue recognition.
  • SOX (for public-co targets) — internal controls over financial reporting.
  • ISO/IEC 25010 — quality (correctness as an SLI).

Resources

  • logic.prompt, README.md, references/saas-billing-and-metering-srs-template.md, references/saas-revenue-recognition-spec-template.md.