CheckoutInstance

The CheckoutInstance represents an active checkout session. It is returned from createCheckout() and provides properties, events, and methods to manage the checkout lifecycle.

Properties

string

Unique identifier for this checkout session.

CheckoutState

Current state of the checkout. See states.

string | null

The order identifier associated with the checkout (available once initialization completes).

boolean

Whether this checkout instance has been destroyed (i.e., cleaned up).

States

State	Meaning
`initializing`	The checkout is loading.
`ready`	The checkout accepts payment details.
`processing`	A payment is in progress.
`action_required`	The payment needs an extra step, such as 3DS.
`updating`	A price update is in progress.
`completed`	The payment succeeded.
`error`	Initialization, a payment, or a price update failed.
`destroyed`	The checkout was destroyed.

Methods

Once you have a CheckoutInstance, you can control or query it with the following methods.

updatePrice(priceId)

Switch the checkout to a different price point without reloading the page.

string

required

The new price point identifier.

While the price updates, the state is updating and the payment buttons are disabled. When the update finishes, the state returns to ready. If FunnelFox Payments Taxes is on, the SDK then recalculates tax and calls onTaxPending and onTaxChange.

await checkout.updatePrice('price_yearly');

The promise rejects in these cases:

Payment in progress: A CheckoutError when the state is processing.
Destroyed checkout: A CheckoutError after destroy().
Empty price: A ValidationError when priceId is empty.
Update failed: The API error. The state changes to error and the 'error' event fires.

getStatus()

Retrieve the current status and details of the checkout session. Returns:

id: Checkout ID
state: Current state
orderId: Order ID (if initialized)
priceId: Current price point ID
isDestroyed: Whether the instance has been destroyed

const status = checkout.getStatus();
console.log(status.id);       // Checkout ID
console.log(status.state);    // Current state
console.log(status.orderId);  // Order ID (if initialized)
console.log(status.priceId);  // Current price point ID
console.log(status.isDestroyed); // Whether the instance has been destroyed

destroy()

Destroy the checkout instance, clean up the embedded UI, and release resources. The instance emits a 'destroy' event, removes all listeners, and can no longer be used.

await checkout.destroy();

Use this method to remove the checkout form, for example when the user navigates away or you want to create a fresh checkout.

isReady()

Returns true if the checkout is in the ready state and not destroyed. Use this to check if calling updatePrice() or allowing user input is safe.

if (checkout.isReady()) {
  console.log('Ready to accept payment');
}

isProcessing()

Returns true while a payment is in progress: in the processing or action_required state. Use it to block actions such as starting another checkout mid-payment.

if (checkout.isProcessing()) {
  console.log('Payment in progress...');
}

isInState(state)

Returns true if the checkout is in the given state.

if (checkout.isInState('updating')) {
  console.log('Price update in progress...');
}

getContainer()

Returns the container element, or null if it’s no longer on the page.

on(), once(), and off()

Subscribe to checkout events:

on(eventName, handler): Call handler every time the event fires.
once(eventName, handler): Call handler the next time the event fires, then remove it.
off(eventName, handler): Remove handler. Leave out handler to remove every handler for the event.

All three return the instance, so you can chain them.

checkout
  .on('success', result => console.log('Order ID:', result.orderId))
  .once('status-change', state => console.log('First state change:', state));

Events

A CheckoutInstance emits these events:

success: The payment succeeded.
error: Initialization or a price update failed.
status-change: The state changed.
destroy: The checkout was destroyed.
purchase-failure: A payment attempt failed.

Learn more about each event and its data in Web SDK events.

API reference

Webhook reference

Billing Web SDK

Properties

States

Methods

updatePrice(priceId)

getStatus()

destroy()

isReady()

isProcessing()

isInState(state)

getContainer()

on(), once(), and off()

Events

​Properties

​States

​Methods

​updatePrice(priceId)

​getStatus()

​destroy()

​isReady()

​isProcessing()

​isInState(state)

​getContainer()

​on(), once(), and off()

​Events

Properties

States

Methods

updatePrice(priceId)

getStatus()

destroy()

isReady()

isProcessing()

isInState(state)

getContainer()

on(), once(), and off()

Events