Readable reference for OpenBilling's shared billing contracts, normalized events, and provider config types.

API Reference

This page describes the current public TypeScript surface by intent, not as a generated symbol dump.

Core types

`BillingProvider`

The shared interface implemented by every adapter.

interface BillingProvider {
  createCheckout(input: CreateCheckoutInput): Promise<CheckoutResult>;
  createPortalLink(input: CreatePortalLinkInput): Promise<PortalLinkResult>;
  verifyWebhook(input: VerifyWebhookInput): Promise<NormalizedWebhookEvent>;
}

Use this when you want app-level portability across providers.

`CreateCheckoutInput`

Input for starting a hosted checkout flow.

Field	Type	Notes
`customerId`	`string \| undefined`	Existing provider customer ID
`customerEmail`	`string \| undefined`	Customer email when the provider should create or identify a customer
`productId`	`string \| undefined`	Used by product-based adapters such as Dodo
`priceId`	`string \| undefined`	Used by price-based adapters such as Stripe
`successUrl`	`string`	Redirect after successful checkout
`cancelUrl`	`string`	Redirect after cancellation
`mode`	`'payment' \| 'subscription'`	Intended billing flow
`metadata`	`Record<string, string> \| undefined`	Optional provider metadata

Important caveat:

Stripe currently requires priceId
Dodo currently requires productId

`CheckoutResult`

Result returned after creating a hosted checkout.

Field	Type	Notes
`id`	`string`	Provider-specific checkout or session ID
`url`	`string`	Hosted checkout URL
`provider`	`BillingProviderName`	The adapter that created the checkout
`raw`	`unknown \| undefined`	Raw provider response

`CreatePortalLinkInput`

Input for creating a billing portal or customer-management link.

Field	Type	Notes
`customerId`	`string`	Provider customer ID
`returnUrl`	`string`	Where the hosted portal should return the user

`PortalLinkResult`

Result returned after creating a hosted portal link.

Field	Type	Notes
`url`	`string`	Hosted portal URL
`provider`	`BillingProviderName`	The adapter that created the link
`raw`	`unknown \| undefined`	Raw provider response

`VerifyWebhookInput`

Input used to verify incoming webhook deliveries.

Field	Type	Notes
`payload`	`string \| Uint8Array`	Raw request body
`signature`	`string \| undefined`	Optional direct signature value
`secret`	`string \| undefined`	Optional per-call secret override
`headers`	`Record<string, string \| undefined> \| undefined`	Raw headers for providers that need them

`NormalizedWebhookEvent`

The normalized event union returned by verifyWebhook.

Active subscription event:

Field	Type	Notes
`type`	`'subscription.active'`	Stable normalized event name
`provider`	`BillingProviderName`	Source provider
`customerId`	`string`	Provider customer ID
`subscriptionId`	`string`	Provider subscription ID
`raw`	`unknown \| undefined`	Raw provider payload

Cancelled subscription event:

Field	Type	Notes
`type`	`'subscription.cancelled'`	Stable normalized event name
`provider`	`BillingProviderName`	Source provider
`customerId`	`string`	Provider customer ID
`subscriptionId`	`string`	Provider subscription ID
`raw`	`unknown \| undefined`	Raw provider payload

Successful payment event:

Field	Type	Notes
`type`	`'payment.succeeded'`	Stable normalized event name
`provider`	`BillingProviderName`	Source provider
`customerId`	`string \| undefined`	Present when the provider includes it
`paymentId`	`string`	Provider payment ID
`raw`	`unknown \| undefined`	Raw provider payload

Fallback event:

Field	Type	Notes
`type`	`'unknown'`	Unsupported or partial event
`provider`	`BillingProviderName`	Source provider
`raw`	`unknown \| undefined`	Raw provider payload

Provider config types

`StripeProviderConfig`

Configuration for createStripeProvider.

Field	Type	Notes
`apiKey`	`string`	Stripe restricted or secret API key
`webhookSecret`	`string`	Stripe webhook signing secret

`DodoProviderConfig`

Configuration for createDodoProvider.

Field	Type	Notes
`apiKey`	`string`	Dodo secret API key
`webhookSecret`	`string`	Dodo webhook signing secret
`baseUrl`	`string \| undefined`	Optional host override

`Provider`

Grouped provider name constants:

Provider.Stripe;
Provider.Dodo;

Use these instead of string literals when possible.

`BillingProviderName`

Union of supported provider names:

type BillingProviderName = 'stripe' | 'dodo';

`BillingMode`

Portable checkout intent:

type BillingMode = 'payment' | 'subscription';

Some providers model this directly. Others infer it from the product or price being purchased.

`Payment`

Grouped payment event constants:

Payment.Succeeded;

`Subscription`

Grouped subscription event constants:

Subscription.Active;
Subscription.Cancelled;

`Webhook`

Grouped fallback event constants:

Webhook.Unknown;

`createBilling`

Typed identity helper for provider construction.

Use this when you want to preserve provider-specific members on top of the shared BillingProvider contract. It returns the same provider object you pass in, while keeping the full subtype visible to TypeScript.

`createStripeProvider`

Factory for the fetch-based Stripe adapter.

Returns a BillingProvider implementation for:

Stripe Checkout Session creation
Stripe Billing Portal links
Stripe webhook verification and normalization

`createDodoProvider`

Factory for the fetch-based Dodo adapter.

Returns a BillingProvider implementation for:

Dodo checkout creation
Dodo customer portal links
Dodo webhook verification and normalization

API Reference

On this page