​

The pricing-preview pipeline

• POST /billing/aiaas-usage-pricing/preview — AI usage charges
• POST /billing/marketplace-rev-share/preview — marketplace builder payouts
• POST /billing/resolution-usage-meter/preview — pay-per-resolution metering
• POST /billing/margin-rollup/preview — reseller margin + revenue share
• POST /billing/payout-ledger/preview — partner payout ledger + statement

​

Purpose — a projection oracle, not a ledger and not a simulator

​

Input catalog — the six engines each fan-in reads

• resolution-usage-meter — projectResolutionUsageEvents, aggregateResolutionMeter, buildResolutionInvoiceLineItems: projects confirmed AI resolutions into idempotent usage events, rolls them into a meter, see them as line items.
• margin-rollup — computeMarginRollup, computeResellerRevenueShareStatement, and the MarginLine / MarginGroup types: rolls reseller lines (revenue, COGS) into sub-account / channel / region margins, and computes a partner revenue-share statement from the same rollup.
• payout-ledger — computePartnerPayoutLedger, computePartnerPayoutStatement, and the PayoutLedgerEntry / PayoutLedgerComputedEntry types: folds accrual, payout, and adjustment events into a running balance, then cuts a period statement.
• marketplace-rev-share — computeMarketplaceRevShare, aggregateBuilderPayouts: splits metered marketplace invocations into gross, platform fee, and per-builder payout.
• aiaas-usage-pricing — computeAiaasUsageCharges: estimates AI usage across the three billable axes (messages, voice minutes, resolved outcomes).
• outcome-pricing — outcomePricingConfigSchema: the config schema the resolution-meter preview validates against.

​

Aggregation envelope — one org-scoped response per endpoint

​

Reading it — preview vs dashboard calculator vs the real charge path

• “What did I already spend?” — read the wallet ledger or the usage-records feed. The preview never substitutes for the posted record.
• “What would this month look like?” — post the candidate usage to the relevant preview endpoint and read the projected breakdown.
• “What if I change the rate?” — use the pricing calculator / what-if simulator, which vary the rate card, not the usage.

​

Glossary

• Margin line — one reseller profitability input: a sub-account, channel, optional region, its revenue, and its cost of goods. margin-rollup folds a set of these into margins.
• Revenue share — a partner’s negotiated percentage (basis points) of the net margin a reseller earned, computed from the same margin rollup so the statement agrees with the rollup.
• Payout ledger entry — one accrual, payout, or adjustment event on a partner’s ledger, with a running balance after each entry.
• Projected invoice line item — a line the resolution meter would emit on an invoice if the period closed now; a descriptor, not a posted line.

​

Worked example — reseller margin + partner revenue share

POST /billing/margin-rollup/preview
Authorization: Bearer <api key>
Content-Type: application/json

{
  "currency": "usd",
  "lines": [
    {
      "subaccount_id": "leaf_acme",
      "channel": "sms",
      "region": "US",
      "currency": "usd",
      "revenue_minor": 120000,
      "cost_minor": 82000,
      "quantity": 4000
    },
    {
      "subaccount_id": "leaf_acme",
      "channel": "voice",
      "region": "US",
      "currency": "usd",
      "revenue_minor": 30000,
      "cost_minor": 19100,
      "quantity": 600
    }
  ],
  "revenue_share": {
    "partner_id": "partner_wl",
    "partner_revenue_share_bps": 2500,
    "period_start": "2026-09-01",
    "period_end": "2026-09-30"
  }
}

{
  "data": {
    "currency": "usd",
    "totals": {
      "revenue_minor": 150000,
      "cost_minor": 101100,
      "margin_minor": 48900,
      "margin_pct_bps": 3260,
      "quantity": 4600,
      "line_count": 2
    },
    "by_channel": [
      {
        "key": "sms",
        "revenue_minor": 120000,
        "cost_minor": 82000,
        "margin_minor": 38000,
        "margin_pct_bps": 3167,
        "quantity": 4000,
        "line_count": 1
      }
    ],
    "revenue_share_statement": {
      "partner_id": "partner_wl",
      "currency": "usd",
      "period_start": "2026-09-01",
      "period_end": "2026-09-30",
      "partner_revenue_share_bps": 2500,
      "gross_revenue_minor": 150000,
      "cost_of_goods_minor": 101100,
      "net_margin_minor": 48900,
      "partner_share_minor": 12225,
      "platform_retained_minor": 36675,
      "line_items": [
        {
          "subaccount_id": "leaf_acme",
          "revenue_minor": 150000,
          "cost_minor": 101100,
          "margin_minor": 48900,
          "partner_share_minor": 12225
        }
      ]
    }
  }
}

​

Worked example — marketplace builder payout projection

POST /billing/marketplace-rev-share/preview
Authorization: Bearer <api key>
Content-Type: application/json

{
  "invocations": [
    { "listingId": "lst_recorder", "builderOrgId": "org_builder1", "consumerOrgId": "org_acme" },
    { "listingId": "lst_recorder", "builderOrgId": "org_builder1", "consumerOrgId": "org_acme" },
    { "listingId": "lst_summary", "builderOrgId": "org_builder2", "consumerOrgId": "org_acme" }
  ],
  "pricingByListing": {
    "lst_recorder": { "enabled": true, "perCallPriceMicroCents": 120000, "platformFeeBps": 1500 },
    "lst_summary":   { "enabled": true, "perCallPriceMicroCents": 50000,  "platformFeeBps": 1500 }
  }
}

{
  "data": {
    "breakdown": {
      "totalGrossMicroCents": 290000,
      "totalPlatformFeeMicroCents": 4350,
      "items": [
        { "listingId": "lst_recorder", "builderOrgId": "org_builder1", "grossMicroCents": 240000, "platformFeeMicroCents": 3600 },
        { "listingId": "lst_summary", "builderOrgId": "org_builder2", "grossMicroCents": 50000, "platformFeeMicroCents": 750 }
      ]
    },
    "payouts": [
      { "builderOrgId": "org_builder1", "netMicroCents": 236400, "grossMicroCents": 240000 },
      { "builderOrgId": "org_builder2", "netMicroCents": 49250, "grossMicroCents": 50000 }
    ]
  }
}

​

Boundary — what the projection layer is not

• Not the ledger. The billing and wallet model and wallets, credits, and charges cover money that moved. A preview never reads or writes the wallet.
• Not an invoice. Billing documents owns the post-close receivable a provider issues. A preview is pre-close by definition and becomes non-authoritative at close.
• Not the raw usage feed. Usage metering pipeline owns the raw usage record feed the meters roll. A preview consumes candidate inputs, never the posted feed.
• Not a rate simulator. The pricing calculator varies the rate card; the preview varies the usage. They answer different “what if” questions.

​

Related

• Billing and wallet — what moved
• Usage metering pipeline — raw usage feed
• Billing documents model — post-close invoice
• Usage records model — per-record billing feed
• Pricing calculator — what-if rate simulation
• Wallets, credits, and charges — ledger attribution