> ## Documentation Index
> Fetch the complete documentation index at: https://funnelfox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ResponseField name="id" type="string">
  Unique identifier for this checkout session.
</ResponseField>

<ResponseField name="state" type="string">
  Current state of the checkout. Possible values: `"initializing"`, `"ready"`, `"processing"`, `"completed"`, `"error"`, or `"action_required"`.
</ResponseField>

<ResponseField name="orderId" type="string">
  The order identifier associated with the checkout (available once initialization completes).
</ResponseField>

<ResponseField name="isDestroyed" type="boolean">
  Whether this checkout instance has been destroyed (i.e., cleaned up).
</ResponseField>

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

<ParamField path="priceId" type="string" required>
  The new price identifier to switch to.
</ParamField>

<Warning>
  You cannot call `updatePrice` while a payment is already in progress (while in the `"processing"` state).
</Warning>

```javascript theme={null}
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

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
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.

```javascript theme={null}
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:**

<ResponseField name="orderId" type="string">
  The order identifier
</ResponseField>

<ResponseField name="status" type="string">
  Transaction status (e.g. `"succeeded"`)
</ResponseField>

<ResponseField name="transactionId" type="string">
  The transaction identifier
</ResponseField>

### error

Emitted when the checkout encounters an error or the payment fails. The handler receives an error object.

```javascript theme={null}
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:**

<ResponseField name="message" type="string">
  Description of the issue
</ResponseField>

<ResponseField name="code" type="string">
  Error code (if available)
</ResponseField>

<ResponseField name="requestId" type="string">
  Request identifier for debugging
</ResponseField>

### status-change

Emitted whenever the checkout's state changes. The handler is called with the new state and the previous state.

```javascript theme={null}
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.

```javascript theme={null}
checkout.on('destroy', () => {
  console.log('Checkout cleaned up');
});
```