# Checkout

Learn how checkout is rendered and customized in Finqu storefronts. This guide covers theme structure, rendering, and available components.
For more detailed information on checkout, contact Finqu support when you start a new checkout customization.

## Overview

The checkout theme in Finqu is structured similarly to the main store theme, but with some important differences. The checkout uses its own set of templates and does not support sections or blocks. Instead, all layout and content are defined directly in the Liquid templates.

## Directory Structure

A typical checkout theme includes:

- **assets/**: Stylesheets (such as `main.scss.liquid`), mixins, and other static files.
- **config/**: Configuration files like `settings_schema.json` and `settings_data.json` for theme settings.
- **layout/**: Layout files, such as `theme.liquid` and `order.liquid`, that define the overall page structure.
- **locales/**: Translation files for different languages (e.g., `en.json`, `fi.json`, `sv.json`).
- **templates/**: Page templates for the checkout flow: `checkout.liquid`, `complete.liquid`, `download.liquid`, `order.liquid`, `orders.liquid`, and `return.liquid`.
- **snippets/**: (Optional) Reusable Liquid code snippets.

`orders.liquid` renders the customer's order history. It replaces the deprecated storefront template `customers/orders.liquid`. Use `order.liquid` for a single order detail page.

### Checkout vs storefront themes

| Feature | Storefront theme | Checkout theme |
|---------|------------------|----------------|
| Sections and blocks | Yes | No — edit templates directly |
| `{% form %}` tag | Yes | No |
| `{% section %}`, `{% sections %}`, `{% block %}`, `{% container %}` | Yes | No |
| `{% layout %}`, `{% render %}`, `{% stylesheet %}`, `{% javascript %}` | Yes | Yes |
| Vue checkout components | No | Required |

Checkout Liquid objects (`order`, `session`, `store`, etc.) are documented separately. See [Checkout objects](/reference/liquid/objects/checkout/global).

### Settings schema

Checkout themes use `config/settings_schema.json` like storefront themes. You can set `api_version` (default `1.2`) to declare which checkout data shape your templates expect.

### Locales

Add translation files under `locales/` (e.g. `en.json`, `fi.json`) the same way as storefront themes. Checkout strings used by Vue components are loaded from your locale files.

### Layout variants

Checkout themes may ship multiple layouts — for example `layout/theme.liquid` for the main flow and `layout/order.liquid` for order confirmation. Portal checkouts can use alternate header layouts.

## Rendering Process

- **Liquid Templates:**
  All static and dynamic content for the checkout is defined in Liquid templates. There are no sections or blocks—customization is done by editing the template files directly.

- **Vue.js Library:**
  All dynamic and interactive features in the checkout are handled by a dedicated Vue.js library. This must be included in your checkout template for features like cart updates, address validation, and payment selection.

  > **Note:** The Vue library is required for the checkout to function correctly. Do not remove or modify the script tag that loads this library.

## Including the Vue Library

Include Bootstrap and the provided Vue.js library in your `checkout.liquid` template. Add the stylesheet in the `<head>`, and load the scripts before the closing `</body>` tag:

```liquid
<link rel="stylesheet" href="https://static.finqu.com/lib-sdk/bootstrap@5.3.8/bootstrap.min.css">

<script src="https://static.finqu.com/lib-sdk/checkout-vue@1.3.6/vue.global.prod.js"></script>
<script src="https://static.finqu.com/lib-sdk/checkout-vue@1.3.6/vue-i18n.global.prod.js"></script>
<script src="https://static.finqu.com/lib-sdk/checkout-vue@1.3.6/customer-portal.umd.js"></script>
<script src="https://static.finqu.com/lib-sdk/bootstrap@5.3.8/bootstrap.bundle.min.js"></script>
```

## Customizing Checkout Styles

You can customize the appearance of the checkout by adding a `checkout.scss.liquid` file to your theme's `assets` directory. This feature may only be available on certain plans.

## Vue Library Documentation

The Vue library provides a set of components and methods to manage the checkout process. The main entry point is the `Checkout` class, which initializes the checkout flow and provides access to various components.

### Basic Usage

```javascript
const checkout = new Checkout();

checkout.initialize(document.querySelector("html").dataset.sessionId).then(() => {
    const app = Vue.createApp({
        inject: ["$checkout"],
        components: checkout.components(),
        // other Vue options
    });

    checkout.setUpApp(app);

    const messages = {};
    messages[checkout.store.state.order.language] = TRANSLATIONS;

    const i18n = VueI18n.createI18n({
        locale: checkout.store.state.order.language,
        fallbackLocale: checkout.store.state.order.language,
        messages: messages
    });

    app.use(i18n);

    app.mount("#checkout");
});

```

## Checkout API

The main `Checkout` class provides the following methods:

| Method | Description |
|--------|-------------|
| `components()` | Returns all available Vue components |
| `dispatchEvent(event, data)` | Dispatches a custom event with optional data |
| `freeze()` | Sets checkout state to "updating" to prevent user interactions |
| `resume()` | Sets checkout state back to "ready" |
| `refresh()` | Refreshes checkout data from the server |
| `placeOrder()` | Initiates the order placement process |

## Available Components

### Cart

Displays the cart contents including line items, gift cards, discounts, and shipping information.

**Props/Slots:**
- Provides slot props: `items`, `giftCards`, `discounts`, `shipping`, `payments`

```vue
<checkout-cart v-slot="{ items, discounts, shipping, payments }">
  <!-- Custom cart rendering -->
</checkout-cart>
```

### Payment Components

#### PaymentMethodSelector

Allows selection from available payment methods.

**Methods:**
- `select(paymentMethod, optionId)`: Select a payment method
- `loading(paymentMethod)`: Check if a payment method is in processing state

```vue
<payment-method-selector />
```

#### PaymentMethodList

Displays available payment methods.

```vue
<payment-method-list />
```

#### KustomCheckout

Integration with Kustom (previous Klarna) checkout solution.

```vue
<klarna-checkout />
```

### User Information Components

#### Contact

Form for collecting and validating contact information.

```vue
<checkout-contact />
```

#### ContactInformation

Displays user's contact information.

```vue
<contact-information />
```

#### Account

Handles user account functionality.

```vue
<checkout-account />
```

### Discount and Promo Components

#### CodeClaim

Input for applying discount/promo codes.

```vue
<code-claim />
```

#### CouponList

Lists applied coupons/discount codes.

```vue
<coupon-list />
```

#### GiftCardList

Displays applied gift cards.

```vue
<gift-card-list />
```

### Shipping Components

#### ShippingMethodSelector

Allows selection of shipping methods.

```vue
<shipping-method-selector />
```

### Utility Components

#### LoadingButton

Button with loading state for asynchronous operations.

```vue
<loading-button :loading="isLoading" @click="handleAction">
  Complete Checkout
</loading-button>
```

#### Timer

Displays countdown timer for checkout session.

```vue
<checkout-timer />
```

#### AppFrame

Container for embedded applications using `@finqu/app-link`.

```vue
<app-frame :src="appUrl" />
```

#### Offer

Displays special offers during checkout.

```vue
<checkout-offer />
```

## Events

The Checkout instance dispatches events that you can listen to:

```javascript
window.addEventListener('Checkout.Event.OrderPlaced', (event) => {
  console.log('Order placed:', event.detail);
});
```

## Best Practices

- Use Liquid templates for all layout and content—sections and blocks are not supported.
- Always include the Vue.js library for checkout functionality.
- Organize your assets, templates, and configuration files logically.
- Test your checkout thoroughly to ensure a seamless customer experience.
- Only use `checkout.scss.liquid` if your plan supports checkout customization.