Skip to content

CheckoutInstance

An active checkout session with properties, events, and methods to manage the checkout lifecycle

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

idstring

Unique identifier for this checkout session.

stateCheckoutState

Current state of the checkout. See states.

orderIdstring | null

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

isDestroyedboolean

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

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.

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

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

priceIdstringrequired

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.

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 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.

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');
}

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...');
}

Returns true if the checkout is in the given state.

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

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

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));

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.