Skip to content
/
Express buttons
Last updated

Express Buttons

The Express Buttons element provides a one-click checkout experience using payment methods like Apple Pay, Google Pay, and Klarna. Unlike passive elements, you must interact with it using its JavaScript API to configure the order and handle the checkout flow.

KSA required

Express Buttons require Kustom Shipping Assistant (KSA) to be configured on your Merchant ID.

There are three ways to initialize the Express Buttons:

  • Order Lines — You provide the cart contents directly. The SDK creates a Kustom Checkout session automatically the first time the consumer interacts with a button. Simplest if you don't already manage Kustom orders yourself.
  • createOrder hook — You provide the cart contents for display, plus a createOrder callback. The SDK invokes the callback when the consumer is about to pay, and you create the Kustom Checkout order yourself and resolve with its order ID. Use this when you want to keep order creation under your control — for example, to avoid creating an order every time a button renders.
  • Order ID — You pass an order ID from an existing Kustom Checkout session. The SDK fetches the cart, currency, and order lines from the backend. Useful when a checkout session already exists.

HTML Element

<kustom-express-buttons id="myButton" locale="sv-se"></kustom-express-buttons>

Attributes

  • locale — The market locale for the checkout (e.g. sv-se). The first part will be used as the language and second part will be used as the country you want to show delivery methods for. See supported locales for the full list.

JavaScript API

Initialize with Order Lines

Use this when you manage the cart yourself and want the SDK to create the Kustom order for you. You provide the order lines and currency directly.

window.kustomElements("express.initialize", "#myButton", {
  currency: "sek",
  orderLines: [
    {
      name: "iPhone 15",
      totalAmount: 18000,
      taxAmount: 3600,
    },
  ],
  shippingAddressRequired: true,
  onConfirm: (response) => {
    window.location.href = response.redirectUrl;
  },
});

Initialize with createOrder hook

Use this when you want full control over when the Kustom order is created — for example, to avoid creating one every time a button renders.

This flow requires shippingAddressRequired: true. The SDK only invokes createOrder once the consumer has interacted with the button and a shipping address is available, which is what triggers the deferred order creation.

Pass your cart contents in orderLines. They are shown to the consumer as the initial total in the express sheet before the real order exists, so use values as close to the final amount (including shipping) as you can. When the consumer is about to pay, the SDK invokes createOrder. Inside it, create the Kustom Checkout order on your backend and resolve with the resulting order_id. The SDK then takes over and uses that order to complete the purchase.

window.kustomElements("express.initialize", "#myButton", {
  currency: "sek",
  orderLines: [
    {
      name: "iPhone 15",
      totalAmount: 18000,
      taxAmount: 3600,
    },
  ],
  shippingAddressRequired: true,
  createOrder: (resolve, reject) => {
    // Create the order on your backend using the Kustom Checkout API,
    // then resolve with { orderId: order_id }.
    fetch("/my-server/create-kustom-order", { method: "POST" })
      .then((res) => res.json())
      .then((order) => resolve({ orderId: order.order_id }))
      .catch(reject);
  },
  onConfirm: (response) => {
    window.location.href = response.redirectUrl;
  },
});

If createOrder rejects (or throws), the purchase attempt is aborted and onError is invoked with a MERCHANT_ABORTED error. If it resolves with a value that is missing orderId, onError is invoked with a MERCHANT_HOOK_INVALID_RESPONSE error instead — use this to distinguish "the consumer / your backend deliberately cancelled" from "the integration is wired up incorrectly".

Initialize with Order ID

Use this when you already have a Kustom Checkout session. The SDK fetches the cart, currency, and order lines from the backend.

window.kustomElements("express.initialize", "#myButton", {
  orderId: "your-kco-order-id",
  shippingAddressRequired: true,
  onConfirm: (response) => {
    window.location.href = response.redirectUrl;
  },
});

If both orderId and createOrder are provided, createOrder is ignored — the order already exists.

Parameters

Order Lines initialization

  • currency — The currency code (e.g. sek).
  • orderLines — Array of order line objects:
    • name — Product or line item name.
    • totalAmount — Total amount for the line in minor units.
    • taxAmount — Tax amount for the line in minor units.
    • quantity — Number of items. Defaults to 1.
  • shippingAddressRequired — Whether to collect a shipping address during checkout.
  • onConfirm — Callback invoked when the consumer confirms. Receives a response object with redirectUrl.

createOrder hook initialization

  • currency — The currency code (e.g. sek).
  • orderLines — Array of order line objects. Used to display an initial total to the consumer before the real order exists, so use values as close to the final amount (including shipping) as you can. Same shape as in Order Lines initialization.
  • createOrder — Callback invoked when the consumer is about to pay. Receives (resolve, reject). Call resolve({ orderId }) with the Kustom Checkout order_id you created on your backend, or reject(error) to abort the purchase. Rejecting (or throwing) surfaces a MERCHANT_ABORTED error; resolving with anything other than { orderId } surfaces MERCHANT_HOOK_INVALID_RESPONSE.
  • shippingAddressRequired — Required, must be true. The createOrder flow only fires after the consumer has shared a shipping address.
  • onConfirm — Callback invoked when the consumer confirms. Receives a response object with redirectUrl.

Order ID initialization

  • orderId — The order ID from an existing Kustom Checkout session.
  • shippingAddressRequired — Whether to collect a shipping address during checkout.
  • onConfirm — Callback invoked when the consumer confirms. Receives a response object with redirectUrl.
Previous page
Next page