IBeam.Billing 2.9.45

IBeam.Billing

IBeam.Billing contains provider-neutral billing contracts and commercial-state models for IBeam-backed applications.

Install this package when shared code needs to describe checkout offers, total-seat pricing, customers, subscriptions, invoices, prices, payment method references, and billing-provider events without taking a dependency on a payment provider or licensing service.

dotnet add package IBeam.Billing

Billing Versus Licensing

Billing answers commercial questions:

• Who is the billing customer?
• What subscription, invoice, contract, marketplace purchase, or support-managed arrangement exists?
• Which provider customer, price, payment method, invoice, or event does this record map to?
• What happened commercially, and what should a reconciler do next?

Licensing answers runtime grant questions:

• Which tenant has the durable product grant?
• Which entitlements are available?
• Which seats are assigned?
• Is the grant currently eligible for runtime use?

Billing should not directly authorize runtime API calls. A reconciler can translate billing events into licensing grants, renewals, suspensions, revocations, seat quantities, and credit grants. Runtime services should continue to enforce access through Licensing and Credits.

Billing Modes

Use BillingModes to represent the commercial model without hard-coding a provider:

Core Models

Offers And Total Seats

An offer quote always represents one license. TotalSeats is the complete seat limit for that license, not an add-on quantity.

var teamOffer = BillingOfferInfo.Create(
    key: "hubbsly-pro-monthly",
    productKey: "hubbsly",
    planKey: "hubbsly-pro",
    displayName: "Hubbsly Pro",
    description: null,
    billingPeriod: "monthly",
    currency: "USD",
    seatPolicy: BillingOfferSeatPolicyInfo.Create(
        defaultTotalSeats: 3,
        minimumTotalSeats: 3),
    pricing: BillingOfferPricingInfo.Create(perSeatAmount: 25m));

var quote = teamOffer.Quote(requestedTotalSeats: 3);
// LicenseQuantity = 1, TotalSeats = 3, TotalAmount = 75

An individual offer uses a default and minimum of one. It can still expand later by quoting a higher total-seat quantity.

Checkout Provider Boundary

Provider adapters implement IBillingCheckoutGateway. The core request carries the IBeam correlation id, offer key, total seats, and return URLs; the adapter returns opaque provider references and hosted URLs.

var gateway = gatewayResolver.Resolve("stripe");
var session = await gateway.CreateCheckoutSessionAsync(
    CreateBillingCheckoutSessionRequest.Create(
        correlationId: purchaseId,
        offerKey: "hubbsly-pro-monthly",
        totalSeats: 3,
        successUrl: new Uri("https://app.example.com/purchase/success"),
        cancelUrl: new Uri("https://app.example.com/plans")));

The same contracts can be implemented by Stripe, PayPal, a marketplace, or an application-owned processor. VerifyWebhookAsync must only return a BillingVerifiedWebhookInfo after the adapter verifies the provider signature. Normalizing verified events and mutating Billing/Licensing state belong to later orchestration layers.

Purchases Before Identity

BillingPurchaseInfo can represent checkout and payment before the buyer has an IBeam user or tenant. TenantId, UserId, and LicenseKey remain empty until later fulfillment and claiming workflows link them.

Purchase creation is idempotent by CorrelationId. Provider updates are idempotent by provider name plus provider event id, so replayed events resolve to the original purchase rather than creating another purchase or future license grant.

Buyer email is normalized for matching but should be retained only as long as the host's onboarding, tax, support, and legal policies require. Call RedactBuyerEmailAsync after the applicable retention window; it removes the email while preserving financial and audit state. Do not place addresses, payment details, raw provider payloads, claim secrets, or access tokens in Metadata.

Tenant And User Ownership

Every durable billing record is tenant-scoped. Records may also carry an optional UserId for single-user purchases, buyer attribution, or account owner display. Enterprise and marketplace flows can leave UserId empty while still linking records to the tenant.

Provider Boundaries

Provider-specific payloads should not live in these public models. Store raw webhook bodies in an app-controlled blob/table and put the safe pointer in PayloadReference. Keep provider secrets and signing keys outside the repository and outside billing records.

Package Relationships