# Client-side events

The KCO JavaScript API allows the parent page to invoke actions and receive events from the Checkout iFrame. It can be used to receive user information and refresh the iFrame when server-side updates have been processed.

## How it’s done - Accessing the JavaScript API

The JavaScript API is available as an object retrieved via the `window._klarnaCheckout` method.  It's accessible after the Checkout iframe is rendered.


```javascript
window._klarnaCheckout(function(api) {
  // Invoke method or register listener
});
```

**Note:** Data received from the JavaScript API should only be used for presentation or to trigger actions.  Integrations should use the Checkout Backend API for fetching data.

## Checkout actions

Two supported actions: suspend and resume.

### Suspend and Resume

This enables the parent page to interact with the Checkout iframe.  When a server-side Kustom call is in progress, `suspend` prevents the user from changing the order, making the iframe unresponsive.  `resume` reactivates user interaction after the server call completes.  `suspend` will automatically `resume` after 10 seconds, which is configurable.

Example usage (suspend and resume):


```javascript
// Suspending the checkout
window._klarnaCheckout(function (api) {
  api.suspend();
});

// Resuming the checkout
window._klarnaCheckout(function (api) {
  api.resume();
});
```

### Disable Auto Resume

To prevent automatic resume after 10 seconds:


```javascript
window._klarnaCheckout(function (api) {
  api.suspend({ 
    autoResume: {
      enabled: false
    }
  });
});
```

## Checkout events

### Registering listeners

Listeners are registered using `api.on()`.  Each key is an event name, and the value is the callback function.


```javascript
window._klarnaCheckout(function(api) {
  api.on({
    'change': function(data) {
      // Do something
    }
  });
});
```

### The "load" event

Triggered when the KCO iframe is rendered.


```json
{
  "customer": {
    "type": "person"
  },
  "shipping_address": {
    "country": "swe",
    "postal_code": "16972"
  }
}
```

* `customer.type`: "person" or "organization"
* `shipping_address.country`: Alpha3 country code
* `shipping_address.postal_code`: Postal code


### The "user_interacted" event

Triggered when the user interacts with the KCO iframe.


```json
{
  "type": "mousedown" // or "keydown"
}
```

### The "customer" event

Triggered when KCO detects or changes customer type.


```json
{
  "type": "person"
}
```

### The "change" event

Triggered when the user changes billing address details (postal code, country, email, etc.) except in AT and DE.


```json
{
  "email": "klara.joyce@klarna.com",
  "postal_code": "12345",
  "country": "deu"
}
```

**Note:** Customer data may not be fully populated in the `data` object. Some fields might be prefilled or obfuscated.

### The "billing_address_change" event

Triggered when KCO detects a valid billing address.


```json
{
  "postal_code": "75511",
  "country": "aut"
}
```

### The "shipping_address_change" event

Triggered when a valid shipping address is detected.  Shipping address is usually the same as the billing address unless specified otherwise.


```json
{
  "postal_code": "75511",
  "country": "aut"
}
```

### The "shipping_option_change" event

Triggered when a shipping option is selected.  Data includes price, `tax_amount`, and `tax_rate` in minor units (e.g., cents).


```json
{
    description: "We will send you a ticket to travel around the world with your goods",
    id: "crazydeal",
    name: "Around the World",
    price: 99999, // cent
    promo: "TODAY ONLY! Fly around the world for FREE* *not actually free",
    tax_amount: 7621, // cent
    tax_rate: 825 // cent
}
```

### The "shipping_address_update_error" event

Generic error event triggered when updating shipping.


```json
{}
```

### The "order_total_change" event

Triggered when the order total changes. Data includes the new total in minor units.


```json
{
  "order_total": 6000
}
```

### The "checkbox_change" event

Triggered when a checkbox is checked/unchecked.


```json
{
  "key": "additional_merchant_terms_checkbox",
  "checked": true
}
```

### The "can_not_complete_order" event

Triggered when the merchant needs to provide alternative payment options.  (e.g. customer declined credit).


```json
{}
```

### The "network_error" event

Triggered if a network issue is detected.


```json
{}
```

### The "redirect_initiated" event

Triggered when the user is about to be redirected to the confirmation page.


```json
true
```

### The "load_confirmation" event

Triggered when the KCO confirmation page renders.


```json
{}
```

### The "validation_callback" event

Triggered when the user clicks **Buy** before the server request. Use this event to run client-side validations. You must call the provided callback with a `should_proceed` value (`true` or `false`) within 10 seconds.

**Note:** `data` is always an empty object in this event. It is included only to maintain the expected handler signature and will not contain any values.

For this feature to work, set `options.require_client_validation` to `true` when creating the checkout order. See the [create checkout order](https://docs.kustom.co/contents/api/checkout/other/createordermerchant#other/createordermerchant/t=request&path=options/require_client_validation) documentation for details.


```javascript
api.on({
  'validation_callback': function (data, callback) {
    callback({ should_proceed: true, message: 'Sorry, your shipping address is not supported.' })
  }
})
```