Create checkout programmatically

Creates and opens a new checkout session for a given price and customer, and renders the payment UI on the page. This is the primary method to initiate a subscription checkout.

You can customize the checkout appearance and styles. Learn more about checkout customization.

Parameters

orgId

string

required

Your organization ID, if not already configured globally. Useful if you did not call configure() or need to override it for this checkout.

priceId

string

required

The price identifier for the subscription or product.

customer

object

required

Customer information.

Show customer properties

externalId

string

required

Your internal identifier for the user.

string

required

Customer’s email address.

countryCode

string

ISO country code for the customer (if applicable).

container

string

required

A CSS selector for the DOM element where the checkout form will be mounted.

Show container styling requirements

When using the default skin, the container element must have the following CSS properties for proper display of the loading indicator:

#checkout-container {
  position: relative;
  min-height: 200px; /* Adjust based on your layout */
}

position: relative: Required because the loading overlay uses position: absolute to cover the container
min-height: Required to ensure the loader is visible during initialization. Recommended minimum is 200px

clientMetadata

object

Additional metadata to associate with this checkout or customer. This data will be passed through to your backend.

cardSelectors

object

Custom CSS selectors for card input fields. If not provided, FunnelFox will auto-generate the payment form.

Show Card selector properties

cardNumber

string

required

CSS selector for an empty <div> where the hosted card number input is injected.

expiryDate

string

required

CSS selector for an empty <div> for the hosted expiry input.

cvv

string

required

CSS selector for an empty <div> for the hosted CVV input.

button

string

required

CSS selector for a <button> element. The SDK hooks its click event for form submission.

cardholderName

string

CSS selector for an <input> element. The SDK reads its value directly.

emailAddress

string

CSS selector for an <input> element. The SDK reads its value directly.

paymentButtonSelectors

object

Custom CSS selectors for payment buttons. Resolved relative to document, not the container.

Show Payment button selector properties

paypal

string

required

CSS selector for a <div> where the PayPal button is rendered.

googlePay

string

required

CSS selector for a <div> where the Google Pay button is rendered.

applePay

string

required

CSS selector for a <div> where the Apple Pay button is rendered.

paymentMethodOrder

array

Array of payment method identifiers to control the display order. Available values: 'PAYMENT_CARD', 'PAYPAL', 'GOOGLE_PAY', 'APPLE_PAY'. Defaults to ['APPLE_PAY', 'GOOGLE_PAY', 'PAYPAL', 'PAYMENT_CARD'].

onInitialized

function

Callback invoked when the checkout has been initialized and is ready.

onSuccess

function

Callback to execute when the payment is successful. An alternative to listening for the 'success' event.

onError

function

Callback for handling errors. Alternative to the 'error' event.

onStatusChange

function

Callback invoked on every status change. Alternative to the 'status-change' event.

Returns

A Promise<CheckoutInstance> that resolves to a CheckoutInstance object representing the checkout session. You can use this object to monitor events or perform actions on the active checkout.

Example

import { createCheckout } from '@funnelfox/billing';

const checkout = await createCheckout({
  // Required
  priceId: 'price_123',
  customer: {
    externalId: 'user_456',
    email: 'user@example.com',
    countryCode: 'US', // Optional
  },
  container: '#checkout-container',

  // Optional
  orgId: 'your-org-id', // If not configured globally
  clientMetadata: { source: 'web' },
  cardSelectors: {
    // Custom card input selectors (optional, defaults to auto-generated)
    cardNumber: '#cardNumberInput',
    expiryDate: '#expiryInput',
    cvv: '#cvvInput',
    cardholderName: '#cardHolderInput',
    emailAddress: '#emailInput',
    button: '#submitButton',
  },
  paymentButtonSelectors: {
    paypal: '#paypalButton',
    googlePay: '#googlePayButton',
    applePay: '#applePayButton',
  },
  paymentMethodOrder: ['APPLE_PAY', 'GOOGLE_PAY', 'PAYPAL', 'PAYMENT_CARD'], // Optional

  // Callbacks (alternative to events)
  onInitialized: () => {
    /* ... */
  },
  onSuccess: result => {
    /* ... */
  },
  onError: error => {
    /* ... */
  },
  onStatusChange: (state, oldState) => {
    /* ... */
  },
});

API reference

Webhook reference

Billing Web SDK

Create checkout programmatically

Parameters

Returns

Example

​Parameters

​Returns

​Example

Parameters

Returns

Example