Unique identifier for this checkout session.
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.
Properties
Section titled “Properties”idstringstateCheckoutStateCurrent state of the checkout. See states.
orderIdstring | nullThe order identifier associated with the checkout (available once initialization completes).
isDestroyedbooleanWhether this checkout instance has been destroyed (i.e., cleaned up).
States
Section titled “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
Section titled “Methods”Once you have a CheckoutInstance, you can control or query it with the
following methods.
updatePrice(priceId)
Section titled “updatePrice(priceId)”Switch the checkout to a different price point without reloading the page.
priceIdstringrequiredThe 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
CheckoutErrorwhen the state isprocessing. - Destroyed checkout: A
CheckoutErrorafterdestroy(). - Empty price: A
ValidationErrorwhenpriceIdis empty. - Update failed: The API error. The state changes to
errorand the'error'event fires.
getStatus()
Section titled “getStatus()”Retrieve the current status and details of the checkout session.
Returns:
id: Checkout IDstate: Current stateorderId: Order ID (if initialized)priceId: Current price point IDisDestroyed: Whether the instance has been destroyed
const status = checkout.getStatus();console.log(status.id); // Checkout IDconsole.log(status.state); // Current stateconsole.log(status.orderId); // Order ID (if initialized)console.log(status.priceId); // Current price point IDconsole.log(status.isDestroyed); // Whether the instance has been destroyeddestroy()
Section titled “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()
Section titled “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()
Section titled “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)
Section titled “isInState(state)”Returns true if the checkout is in the given state.
if (checkout.isInState('updating')) { console.log('Price update in progress...');}getContainer()
Section titled “getContainer()”Returns the container element, or null if it’s no longer on the page.
on(), once(), and off()
Section titled “on(), once(), and off()”Subscribe to checkout events:
on(eventName, handler): Callhandlerevery time the event fires.once(eventName, handler): Callhandlerthe next time the event fires, then remove it.off(eventName, handler): Removehandler. Leave outhandlerto 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
Section titled “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.