Skip to main content
The FunnelFox Billing Web SDK is a modern JavaScript library for subscription payments, with built-in integration for Primer’s Universal Checkout. It provides a clean, promise-based API, event-driven architecture, robust error handling, and full TypeScript support.

​
Key features

  • TypeScript-first: Full type definitions and JSDoc coverage out of the box.
  • Dynamic pricing: Update prices on the fly without page reloads.
  • Event-driven: Subscribe to lifecycle events for success, errors, and state changes.
  • Production-ready: Built-in validation, retries, and structured errors.
  • Lightweight: ~15KB minified with minimal dependencies.
  • Browser support: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+. Internet Explorer is not supported.
Check out complete integration examples to see the SDK in action and get started quickly.

​
Get started

​
1. Install

You can install the Billing SDK either by including it via a CDN or by using NPM.
Primer’s Web SDK must be loaded first on the page before the FunnelFox Billing SDK.
  • CDN
  • NPM
Include Primer’s Universal Checkout scripts and styles, then include the FunnelFox Billing SDK script:
<!-- Include Primer SDK first -->
<script src="https://sdk.primer.io/web/v2.57.3/Primer.min.js"></script>
<link rel="stylesheet" href="https://sdk.primer.io/web/v2.57.3/Checkout.css" />

<!-- Include FunnelFox Billing SDK -->
<script src="https://unpkg.com/@funnelfox/billing@0.1.0/dist/funnelfox-billing.min.js"></script>

​
2. Configure

Configure the SDK once at startup with your organization info and any custom settings. Use the configure() function to set global options that apply to all subsequent checkout operations. 
import { configure } from '@funnelfox/billing';

configure({
  orgId: 'your-org-id',       // **Required**: your organization ID
  baseUrl: 'https://custom.api', // Optional: custom API endpoint (default is https://billing.funnelfox.com)
  region: 'us-east-1',        // Optional: region identifier (default is "default")
});
Parameters:
​
orgId
string
required
Your organization’s ID (required for all operations). Must be provided either in configure() or in each API call.
​
baseUrl
string
default:"https://billing.funnelfox.com"
Custom API base URL if you are pointing to a non-default backend.
​
region
string
default:"default"
Deployment region to use (if applicable).
It’s recommended to call configure() once with your orgId so you don’t need to pass it every time. If configure() is not called, you must include orgId in the options of each createCheckout or session creation call.

​
3. Create your first checkout

After configuring the SDK, you can create a checkout in just a few lines. For example, to create a checkout for a given price and customer and render it on your page: 
import { createCheckout } from '@funnelfox/billing';

await createCheckout({
  priceId: 'price_123',
  customer: {
    externalId: 'user_456',
    email: 'user@example.com',
  },
  container: '#checkout-container',
});
Required parameters:
​
priceId
string
required
The price identifier for the subscription or product.
​
customer
object
required
Customer information (requires externalId and email).
​
container
string
required
A CSS selector for the DOM element where the checkout form will be mounted.
After calling createCheckout(), the Primer-powered checkout form will appear in the specified container, ready for the user to complete payment.
Learn about all available createCheckout parameters, including optional callbacks and customization options.
⌘I