Billing Integration for Usage-Based Products

Pinion prices and commits usage-based terms — it captures the negotiated rate card (included entitlement plus graduated or volume overage tiers) on the closed deal and persists it to the contract. Pinion does not meter actual consumption, rate usage events, or produce invoices. Those are the job of a billing system.

That split is deliberate: Pinion is the system of record for the commercial terms, and you bring your own billing engine to do the metering and invoicing. This page is the contract between the two — what Pinion persists, how to read the full rate card, and how to know when a new commitment is ready to sync.

The boundary — what Pinion does and doesn’t do

If you meter usage in your product and rate it in Stripe Billing, Metronome, Orb, Zuora, or Salesforce Revenue Cloud consumption schedules, Pinion’s role is to hand that system the contracted terms from the closed deal. If you run a homegrown biller off a data warehouse, the same terms are what you export.

Where the terms live

The rate card exists in three places, from catalog definition down to the committed contract.

1. The rate-card definition (catalog)

Authored by a Product Manager on the product (see Usage & Metered Billing). A product is usage-based when Product2.UsageBased__c is true.

• UsageDimension__c — the metered dimension: UnitOfMeasure__c, Entitlement__c (included units), BillingCadence__c, OverageRateUplift__c / OverageRateUpliftType__c, Product__c.
• UsageRate__c — a rate schedule for that dimension, scoped by Pricebook__c and versioned by EffectiveFrom__c / EffectiveTo__c. Its PricingModel__c is the overage model: Slab (graduated) or Range (volume).
• UsageRateTier__c — the ladder itself: LowerBound__c, UpperBound__c (blank = open-ended top band), Rate__c, child of UsageRate__c.

2. The committed terms on the deal (line item)

When a usage-based product is configured, Pinion stamps the committed terms onto the OpportunityLineItem / QuoteLineItem (twin fields — see Field Propagation):

UsageDimension__c, UsageEntitlement__c, UsageUnitOfMeasure__c, OverageRate__c, OverageRateUplift__c, EstimatedUsage__c, ProjectedOverage__c.

3. The contracted terms (subscription)

On close-won, the committed terms persist to Subscription__c:

UsageDimension__c, UsageEntitlement__c, UsageUnitOfMeasure__c, OverageRate__c.

This subscription record is your integration handoff: it is the contracted, active commitment your biller reads.

Resolving the full tier ladder

The subscription stores the headline terms — included entitlement, unit of measure, and a single OverageRate__c — plus a UsageDimension__c pointer. It does not store the full tier ladder. To rate overage you need the complete schedule, which you resolve by joining out from the dimension:

1. From Subscription__c.UsageDimension__c, find the UsageRate__c rows for that dimension.
2. Select the one whose Pricebook__c matches the deal’s price book and whose EffectiveFrom__c / EffectiveTo__c window spans the contract’s effective date.
3. Read its PricingModel__c (Slab vs Range) and its child UsageRateTier__c rows, ordered by LowerBound__c.

Slab vs Range — apply the right math

The model matches Salesforce CPQ semantics, so a biller that already speaks CPQ needs no translation:

• Slab (graduated) — each tier prices only the units that fall within its band, like tax brackets.
• Range (volume) — all overage units are priced at the single tier the total lands in.

Rating the same usage under the wrong model produces a different number, so read PricingModel__c per rate card and apply the matching calculation.

Knowing when to sync — the change signal

Pinion publishes the SubscriptionChanged__e platform event when a subscription is created or changed. Subscribe to it (or enable Change Data Capture on Subscription__c) to drive your billing sync instead of polling.

Payload: SubscriptionId__c, ContractId__c, AccountId__c, ProductId__c, ChangeType__c, EffectiveDate__c.

The event is a thin notification — it carries the keys and the change type, not the terms themselves. On receipt, re-query the subscription and resolve its rate card (above), then push to your billing system. Keeping the terms out of the event payload is intentional: the record stays the single source of truth, and a late subscriber always reads current state.

Recommended pattern

1. A usage-based deal closes; Pinion creates the Subscription__c with the committed terms and fires SubscriptionChanged__e.
2. Your integration middleware (MuleSoft, a Flow, or an external event/CDC listener) receives the event.
3. It queries the subscription and joins the rate-card ladder (UsageDimension__c → effective UsageRate__c → UsageRateTier__c).
4. It maps the terms into your billing system’s contract/price model, where you meter real usage and rate + invoice it.

Reading terms with an AI assistant

If you have Pinion’s AI Assistant Access (MCP) connected, the EstimatePrice tool already projects usage-based deals, so an assistant can read and explain a deal’s usage terms in natural language. That is a read/explain path for people, not a billing sync path — it complements, and does not replace, the record-and-event contract above.

Related

• Usage & Metered Billing — authoring the rate card and how usage pricing behaves.
• Field Propagation — the twin-field carry for the committed line-level terms.
• Config Promotion — moving rate-card configuration (UsageDimension__c / UsageRate__c / UsageRateTier__c, keyed by SyncKey__c) across orgs.