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. In order to complete your integration and perform a checkout you will have to also implement the Platform Interface, but you can defer this until you get a feel for how the button will appear for your shoppers.

Loading the SDK

In your document's head, include the SDK

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

Rendering the button

Once the sdk has been installed you will have access to the Simpler object (either as a global variable, or by importing * from the npm package). The Simpler object contains a single function, called checkout that handles rendering 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

In case where you have a complex product page and want to adjust the cart based on user selection, you can use the setItems function 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,
    },
  ],
});

// Example 1 : a select element where the user can select their preferred variation
const dropdown = document.querySelector("select#variation-select");
dropdown.addEventListener("change", (evt) => {
  simplerCheckout.setItems([
    {
      id: "product-id",
      quantity: 1,
      attributes: {
        "variation-attribute": evt.target.value,
      },
    },
  ]);
});

// Example 2 : an input where the user can select their desired quantity
const quantityInput = document.querySelector('input[name="quantity"]');
quantityInput.addEventListener("change", (evt) => {
  simplerCheckout.setItems([
    {
      id: "product-id",
      quantity: evt.target.value,
    },
  ]);
});

// Example 3 : a checkbox that adds a complimentary product to the cart
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 },
  ]);
});

// Example 4 : set metadata for the cart that will be created
simplerCheckout.setMetadata({
  key: "Value",
});

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(item);
  },
});

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. It is a function that accepts a single argument which is the ID of the order that was placed on your platform after the shopper's checkout.

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

Customizing the button appearance

The Simpler Button is a custom web component that utilizes a shadow DOM. As such its core styling cannot be overridden by any CSS code you write. This is a deliberate decision on our side, since the button is continuously evolving with input from the whole Simpler network and utilizes best practices for compatibility with multiple browsers and accessibility for all.

The customization you can perform on the button focuses on two points : Sizing and the optional separator.

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

The separator is an ornamental element used to separate the different ways your shopper can follow to complete their checkout journey. By selecting the top, bottom or marquee separator and supplying it to the checkout argument you can trigger the visibility of the releveant separator.

Full Parameters Reference

Property	Accepted Value(s)	Default Value
appId	A valid UUID string	Required
target	A valid HTML Element	Required
currency	A valid ISO 4217 currency code (i.e USD)	Required
placement	product_page | cart_page | checkout_page | minicart | string	Required
locale	en | fr | it | es | el	en
separator	top | bottom | marquee	null
items	This property holds an array of cart items.	[]
items[0].id	The product identifier.	Required
items[0].quantity	The product's cart quantity.	1
items[0].attributes	A key-value pair of attribute code and its related value id.	[]
showPaymentMethods	A boolean value regarding the payment method options visibility.	true
onSuccess	A callback function which will be invoked once order has been successfully submitted from Simpler to the remote API. This callback provides the orderId.	null
setMetadata	A callback function which will set the metadata for the cart to be created. This will replace any metadata previously set.	null
onBeforeCheckout	A callback function which will be invoked before the checkout window opens up. It's arguments are items, setMetadata, setItems, setLocale. If false is explicitly return, then the checkout window won't open at all.	null

Callback Arguments

onSuccess

{
  orderId: string;
  metadata: Record<string, unknown>;
  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;
      };
    };
    fees: {
      title: string;
      amount: number;
    }[];
    totals: {
      items: number;
      shipping: number;
      discount: number;
      totalPayable: number;
      loyaltyDiscountCents: number;
      fees: number;
    };
  }
}