> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Checkout

The Checkout screen renders a full subscription checkout flow for a customer. Mount it when you want to let a customer initiate a new subscription.

---

![The Checkout screen rendered by the SDK](/_fern-img/a38231fdc1e13dda7a6cc1e65afc524fd5868654b39f23be9dbfeef4b30d634b.webp)

---

## Overview

Checkout is driven by a `portalObject` your backend generates for a specific pricing plan. The SDK uses it to load the correct plan, pricing, and payment options for that customer. Your frontend never handles API keys directly.

The screen emits two events: `ready` when the checkout has loaded, and `error` if something goes wrong.

## Mount the screen

**`Checkout screen`**

```js Checkout screen
import { createSolvimonCore } from '@solvimon/solvimon-web/core';

// Generated by your backend via the Solvimon API.
const checkoutPortalObject = {
    object_type: 'PORTAL_URL',
    id: 'purl_example',
    type: 'INIT_PRICING_PLAN_SUBSCRIPTION',
    pricing_plan_id: 'ppl_example',
    token: 'replace-with-a-real-portal-token',
    status: 'PUBLISHED',
};

const solvimon = createSolvimonCore({
    environment: 'TEST',
    locale: 'en-US',
    branding: {
        colors: {
            primary: '#1d4ed8',
            secondary: '#0f172a',
        },
    },
});

const unmount = solvimon.createScreen('checkout', {
    container: '#sdk-root',
    portalObject: checkoutPortalObject,
    configuration: {
        email: 'john@example.com',
        countryCode: 'NL',
    },
});

window.addEventListener('beforeunload', () => {
    unmount?.();
});
```

## Configuration

| Option              | Type       | Required | Description                                                                                  |
| ------------------- | ---------- | -------- | -------------------------------------------------------------------------------------------- |
| `email`             | `string`   | No       | Pre-fills the email field in the checkout form. Must be a valid email address.               |
| `countryCode`       | `string`   | No       | Two-letter country code (e.g. `NL`, `US`). Used to show the correct payment methods and tax. |
| `enabledPricingIds` | `string[]` | No       | Restrict which pricing plans are available during checkout.                                  |
| `avatar`            | `string`   | No       | URL of an avatar image shown in the checkout UI.                                             |

## Events

Checkout fires DOM events on the container element.

**`Handling checkout events`**

```js Handling checkout events
const container = document.getElementById('sdk-root');

container.addEventListener('ready', () => {
    console.log('Checkout is ready');
});

container.addEventListener('error', (event) => {
    console.error(event.detail.title, event.detail.message);
});
```

| Event   | Payload                              | Description                                                      |
| ------- | ------------------------------------ | ---------------------------------------------------------------- |
| `ready` | none                                 | Fired when the checkout has loaded and is ready for interaction. |
| `error` | `{ title: string, message: string }` | Fired if an error occurs during checkout.                        |

## URL parameters

You can pre-fill values by appending query parameters to the URL of the page that mounts this screen. Solvimon reads them on load and applies them before the customer interacts with the form. The same parameters work on a [hosted checkout](/platform-guides/customers-and-billing/hosted-checkout) link, where Solvimon hosts the page instead of you.

| Parameter     | Description                                                          |
| ------------- | -------------------------------------------------------------------- |
| `email`       | Pre-fills the email field, same as the `email` configuration option. |
| `coupon_code` | Pre-fills and applies a coupon code to the checkout.                 |

There is no URL parameter for `countryCode` or the other configuration options; pass those through `configuration` when you call `createScreen`.

```
https://your-app.example.com/checkout?email=john@example.com&coupon_code=WELCOME10
```

> **Note**
>
> Values passed via URL parameters take precedence over the `configuration` object passed to `createScreen`.