Using the Javascript SDK

The Simpler Javascript SDK is a lightweight script that allows you to render the Simpler Checkout button anywhere in your storefront with minimal hassle, allowing your shoppers to checkout in seconds.

This guide covers how to load and use the SDK to render and customize the Simpler Button. To complete your integration you will also need to implement the Platform Interface APIs. You can defer that step until you get a feel for how the button will appear for your shoppers.

Loading the SDK

Add the following <script> tag inside your page's <head> element:

<script
  type="text/javascript"
  src="https://cdn.simpler.so/sdk/simpler-checkout.js"
></script>

Rendering the button

Once the SDK has been loaded you will have access to the global Simpler object. It exposes a single function called checkout that renders the button with a predefined cart preloaded. You can then use the return value of this call to update the cart if needed.

// wait for the page to load before trying to append Simpler
window.addEventListener("DOMContentLoaded", () => {
  Simpler.checkout({
    appId: "your_merchant_app_id",
    currency: "EUR",
    target: document.getElementById("simpler-container"),
    items: [
      {
        id: "product-id",
        quantity: 1,
      },
    ],
  });
});

This example will search your DOM for an element with the simpler-container id and append our custom web component, that will handle rendering the button. When clicked, the button will open a Simpler Checkout session with a cart containing a single item which will be the product with id product-id.

Reacting to user selections

If you have a complex product page and want to adjust the cart based on user selections, you can use the functions returned by the initial button render.

const simplerCheckout = Simpler.checkout({
  appId: "app_id",
  currency: "EUR",
  target: document.getElementById("simpler-container"),
  items: [
    {
      id: "product-id",
      quantity: 1,
    },
  ],
});

The checkout function returns an object with methods to dynamically update the checkout:

Method	Description
`setItems`	Update the cart items
`setLocale`	Change the button language
`setMetadata`	Set or update cart metadata
`setCoupon`	Apply or change a coupon code
`setRemoteLoyaltyCoupon`	Apply or change a remote loyalty coupon code

Updating product variations

Use setItems to update the cart when a user selects a product variation:

const dropdown = document.querySelector("select#variation-select");
dropdown.addEventListener("change", (evt) => {
  simplerCheckout.setItems([
    {
      id: "product-id",
      quantity: 1,
      attributes: [{ key: "variation-attribute", value: evt.target.value }],
    },
  ]);
});

Updating quantity

Update the quantity when the user changes their selection:

const quantityInput = document.querySelector('input[name="quantity"]');
quantityInput.addEventListener("change", (evt) => {
  simplerCheckout.setItems([
    {
      id: "product-id",
      quantity: Number(evt.target.value),
    },
  ]);
});

Adding upsell products

Add additional products to the cart, such as upsells or bundles:

const includeUpsellCheckbox = document.querySelector(
  'input[name="include_upsell"]'
);
includeUpsellCheckbox.addEventListener("change", (evt) => {
  simplerCheckout.setItems([
    { id: "product-id", quantity: 1 },
    { id: "upsell-product-id", quantity: 1 },
  ]);
});

Setting cart metadata

Attach custom metadata to the cart:

simplerCheckout.setMetadata({
  key: "Value",
});

Applying a coupon code

Pre-apply a coupon code from user input:

const couponInput = document.querySelector('input[name="coupon"]');
couponInput.addEventListener("change", (evt) => {
  simplerCheckout.setCoupon(evt.target.value);
});

Remote loyalty coupons

If you run your own loyalty program, pass the coupon code your shopper already selected on your site so it's pre-applied in Simpler checkout instead of being picked again:

simplerCheckout.setRemoteLoyaltyCoupon("SHOE10");

This is independent of setCoupon — a shopper can have both a regular coupon and a remote loyalty coupon applied at the same time. Your Quote endpoint's loyalty_profile.available_coupons response still determines which codes are valid; an unrecognized code is simply not pre-selected.

Changing the locale

Update the button language dynamically:

simplerCheckout.setLocale("el");

Validate products before the checkout window opens

You can run your own validation for the products to be checked out before the checkout window opens, through the onBeforeCheckout.

const simplerCheckout = Simpler.checkout({
  appId: "app_id",
  currency: "EUR",
  target: document.getElementById("simpler-container"),
  items: [
    {
      id: "product-id",
      quantity: 1,
    },
  ],
  onBeforeCheckout: ({ items }) => {
    return myCustomItemValidation(items);
  },
});

warning

If onBeforeCheckout returns false, the checkout window will not open.

Handling a Successful Checkout

In most cases, you will want the shopper to end up in your storefront's order received (or "thank you") page when they finish their checkout. To handle what happens after a checkout has been completed you can supply the onSuccess callback to the checkout object. The callback receives three arguments: the order ID, any metadata you set, and order details.

const simplerCheckout = Simpler.checkout({
  appId: "app_id",
  currency: "EUR",
  target: document.getElementById("simpler-container"),
  items: [
    {
      id: "product-id",
      quantity: 1,
    },
  ],
  onSuccess: (orderId, metadata, order) => {
    console.log("Order placed:", orderId);
    console.log("Customer:", order.customer.email);
    window.location.href =
      window.location.origin + `/order-received/${orderId}`;
  },
});

Customizing the button appearance

The Simpler Button is a custom web component that uses a shadow DOM. The button's core styles are managed by Simpler to ensure consistent branding, accessibility, and cross-browser compatibility across all stores.

The customization you can perform focuses on two areas: sizing and the optional separator.

The button will resize to fill the available space of its container, as long as it stays within the 260–520 pixel range. You can control the size by resizing the container element with your own CSS.

The separator is an ornamental element used to visually separate the Simpler button from other checkout options. Pass separator: "top", "bottom", or "marquee" as the separator property to display it.

Full Parameters Reference

Required Properties

Property	Accepted Value(s)	Description
`appId`	A valid UUID string	Your merchant application ID
`target`	A valid HTML Element	Container for the button
`currency`	A valid ISO 4217 currency code	e.g. `EUR`, `USD`
`items`	`Array<Item>`	Cart items to checkout. See below

Optional Properties

Property	Accepted Value(s)	Default	Description
`placement`	`product_page` \| `cart_page` \| `minicart` \| string	—	Where the button is placed
`locale`	`en` \| `es` \| `ca` \| `el` \| `it` \| `fr` \| `de` \| `pt`	page language, then `en`	Button language
`separator`	`top` \| `bottom` \| `marquee`	`null`	Ornamental separator style
`showPaymentMethods`	`boolean`	`true`	Show accepted payment method icons
`fullWidth`	`boolean`	`false`	Expand button to fill container width
`compact`	`boolean`	`false`	Use compact button style
`coupon`	`string`	—	Pre-apply a coupon code to the checkout
`remoteLoyaltyCoupon`	`string`	—	Pre-apply a remote loyalty coupon code (see Remote loyalty coupons)
`metadata`	`Record<string, unknown>`	—	Custom metadata to attach to the cart
`onSuccess`	`function`	`null`	Callback invoked after successful order submission. See onSuccess.
`onBeforeCheckout`	`function`	`null`	Callback invoked before checkout opens. Receives `{ items, setMetadata, setItems, setLocale }`. Return `false` to cancel.

Items Array

Property	Accepted Value(s)	Default	Description
`items[].id`	`string`	Required	The product identifier
`items[].quantity`	positive integer (`number`)	`1`	Quantity to add to cart
`items[].attributes`	`Array<{ key: string, value: string }>`	`[]`	Product variation attributes

Callback Reference

onSuccess

The onSuccess callback is invoked after a successful checkout. It receives three arguments:

onSuccess: (orderId: string, metadata: Record<string, unknown>, order: Order) => void

Arguments:

Argument	Type	Description
`orderId`	`string`	The order ID from your platform
`metadata`	`Record<string, unknown>`	Any metadata you set during checkout
`order`	`Order`	Order details (see below)

Order Object:

interface Order {
  customer: {
    email: string;
    firstName: string;
    lastName: string;
  };
  address?: {
    recipientName: string;
    phone: string;
    street: string;
    postcode: string;
    city: string;
    state?: string;
    country: string;
    notes?: string;
  };
  shipping?: {
    id: string;
    title: string;
    boxNowLocker?: {
      lockerId: string;
    };
  };
  pickupPoint?: {
    id: string;
    name: string;
    address: string;
    postcode: string;
    city: string;
    country: string;
    provider: "BOXNOW" | "GLS" | "INPOST" | "SKROUTZ";
    type: "LOCKER" | "STORE";
  };
  fees: Array<{
    title: string;
    amount: number;
  }>;
  totals: {
    items: number;
    shipping: number;
    discount: number;
    totalPayable: number;
    loyaltyDiscountCents: number;
    fees: number;
  };
}

Loading the SDK​

Rendering the button​

Reacting to user selections​

Updating product variations​

Updating quantity​

Adding upsell products​

Setting cart metadata​

Applying a coupon code​

Remote loyalty coupons​

Changing the locale​

Validate products before the checkout window opens​

Handling a Successful Checkout​

Customizing the button appearance​

Full Parameters Reference​

Required Properties​

Optional Properties​

Items Array​

Callback Reference​

onSuccess​