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

# Web SDK events reference

> Complete list of FunnelFox Web SDK events. Track page views, purchases, onboarding steps, and custom events programmatically.

The Billing SDK's checkout process emits several events that you can handle to respond to different stages of the payment flow. You can attach event listeners or you may use the callback options in `createCheckout` for the same events.

<Tip>
  Learn more about [CheckoutInstance](/develop/checkout-instance).
</Tip>

Below is a list of all checkout events and their meanings:

## success

**When it fires:** When a payment is completed successfully and the checkout has finished. This usually means the customer's payment was processed and a subscription or purchase was created.

**Data:** The event handler receives a `PaymentResult` object which includes details about the completed transaction.

<ResponseField name="orderId" type="string">
  The ID of the order/subscription created on Funnelfox.
</ResponseField>

<ResponseField name="status" type="string">
  The status string (e.g. `"succeeded"` for a successful payment).
</ResponseField>

<ResponseField name="transactionId" type="string">
  The transaction identifier (if applicable, e.g. from the payment processor).
</ResponseField>

**Example:**

```javascript theme={null}
checkout.on('success', (result) => {
  console.log('Payment successful, Order ID:', result.orderId);
  console.log('Status:', result.status);       // e.g. "succeeded"
  console.log('Transaction ID:', result.transactionId);
});
```

## error

**When it fires:** When an error occurs during the checkout or the payment fails.

**Data:** The handler receives an `Error` object (which could be one of the SDK's specific error types like `ValidationError`, `APIError`, etc.). You can inspect `error.message` for a human-readable message. Depending on the error type, other properties may be available:

<ResponseField name="message" type="string">
  A human-readable error message.
</ResponseField>

<ResponseField name="code" type="string">
  A short error code string, if provided (e.g. `"invalid_price"`).
</ResponseField>

<ResponseField name="requestId" type="string">
  An ID for the request/transaction, useful when contacting support.
</ResponseField>

**Example:**

```javascript theme={null}
checkout.on('error', (error) => {
  console.error('Checkout error:', error.message);
  if (error.code) {
    console.error('Error code:', error.code);
  }
  if (error.requestId) {
    console.error('Request ID:', error.requestId);
  }
});
```

## status-change

**When it fires:** Whenever the checkout's internal state changes. For example, the checkout might move from `"initializing"` to `"ready"` once it's fully loaded, then to `"processing"` when the user submits payment, and finally to `"completed"` or `"error"`.

**Data:** The handler is called with two arguments: `newState` and `oldState` (both strings). States include `"initializing"`, `"ready"`, `"processing"`, `"action_required"`, `"completed"`, and `"error"`.

**Example:**

```javascript theme={null}
checkout.on('status-change', (newState, oldState) => {
  console.log(`State changed: ${oldState} -> ${newState}`);
  if (newState === 'completed') {
    console.log('Checkout completed successfully!');
  }
});
```

This event is useful for updating UI elements or logging analytics at different stages of the checkout.

## destroy

**When it fires:** When the checkout instance has been destroyed. This can happen if you call `checkout.destroy()` or if the checkout cleans up after completion.

**Data:** No additional data (the handler is simply called with no arguments).

**Example:**

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

Once this event fires, the checkout UI has been removed from the DOM. If the user needs to pay again, you would create a new checkout instance.