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

​
Properties

​
id
string
Unique identifier for this checkout session.
​
state
string
Current state of the checkout. Possible values: "initializing", "ready", "processing", "completed", "error", or "action_required".
​
orderId
string
The order identifier associated with the checkout (available once initialization completes).
​
isDestroyed
boolean
Whether this checkout instance has been destroyed (i.e., cleaned up).

​
Methods

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

​
updatePrice(priceId)

Update the current checkout to use a different price. This allows you to switch the product/plan on the fly.
​
priceId
string
required
The new price identifier to switch to.
You cannot call updatePrice while a payment is already in progress (while in the "processing" state).
await checkout.updatePrice('price_yearly');

​
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 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 ID
console.log(status.isDestroyed); // Whether the instance has been destroyed

​
destroy()

Destroy the checkout instance, clean up the embedded UI, and release resources. After calling destroy(), the CheckoutInstance will emit a 'destroy' event and no longer be usable. 
await checkout.destroy();
This method can be used to remove the checkout form (for example, if the user navigates away or if you want to re-initialize a fresh checkout).

​
isReady()

Returns true if the checkout is fully initialized and ready to accept payment details. 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 if a payment is currently in progress (the checkout is in a processing state). You might use this to prevent certain actions (like triggering another checkout) while a payment is mid-flight. 
if (checkout.isProcessing()) {
  console.log('Payment in progress...');
}

​
Events

You can subscribe to checkout events using the checkout.on(eventName, handler) method. The following events are emitted by a CheckoutInstance:

​
success

Emitted when the payment is completed successfully (the subscription or purchase was created and confirmed). The handler receives a result object containing details of the successful transaction. 
checkout.on('success', result => {
  console.log('Order ID:', result.orderId);
  console.log('Status:', result.status); // e.g. "succeeded"
  console.log('Transaction:', result.transactionId);
});
Result object properties:
​
orderId
string
The order identifier
​
status
string
Transaction status (e.g. "succeeded")
​
transactionId
string
The transaction identifier

​
error

Emitted when the checkout encounters an error or the payment fails. The handler receives an error object. 
checkout.on('error', error => {
  console.error('Error:', error.message);
  console.error('Code:', error.code);
  console.error('Request ID:', error.requestId); // useful for support
});
Error properties:
​
message
string
Description of the issue
​
code
string
Error code (if available)
​
requestId
string
Request identifier for debugging

​
status-change

Emitted whenever the checkout’s state changes. The handler is called with the new state and the previous state. 
checkout.on('status-change', (newState, oldState) => {
  console.log(`${oldState} → ${newState}`);
  // States can be: "initializing", "ready", "processing", "action_required", "completed", or "error"
});
This event is useful for tracking the user’s progress through the checkout (for example, to update your UI or analytics).

​
destroy

Emitted when the checkout instance is destroyed (manually or automatically). After this event, the checkout UI is removed and the instance can no longer be used. 
checkout.on('destroy', () => {
  console.log('Checkout cleaned up');
});
⌘I