Bonsai Checkout

This document explains how to use the Bonsai Checkout, and guides you through the process of integrating it with your website.

Integrations

There are 2 ways to integrate with Bonsai Checkout:

Embedded - embedding the Bonsai Checkout in your website
Hosted - redirecting to a secure Bonsai Checkout URL

Based on your preferred experience, choose the one that fits your needs.

Embedded

This integration enables you to run the checkout process on your domain.

You can obtain the order information after a successful checkout through callbacks, explained in the following sections.

Query parameters

Checkout app reads the following query parameters from the URL:

Name	Value	Description	Required
`bonsai`	`checkout_ID`	Starts checkout process using provided cart ID	Yes

Example

https://your.domain.com/checkout?bonsai=checkout_abcdef

bonsai parameter is the only required parameter, and it should be provided with a cart id that you want to check out.

Callbacks

Callbacks are optional, and you can use them to obtain order information after a successful checkout. These functions must be provided to the init function (further details in step 3 section).

Example

function handleOrder (order) {
  // do something with the order
};

bonsai.init({
  // ...
  bonsaiEvents: {
    version: 'v1',
    onBonsaiEvent: ({ tag, event, data }) => {
      switch (tag) {
        case 'order_completed':
          handleOrder(event);
          break;
        case 'product_unavailable':
          console.log('Product unavailable', data);
          break;
      }
    },
  },
  // ...
});

Step 1: Create a page

You will need to create a page on your website that will host the Bonsai Checkout, e.g. https://your.domain.com/checkout. We will refer to this page as the Checkout page.

Step 2: Add Bonsai Checkout dependencies

Add the Bonsai Checkout dependencies to Checkout page:

checkout.html
<head>
  <!-- Bonsai Checkout CSS -->
  <link rel="stylesheet" href="https://ui.getbonsai.com/index.css" />
</head>

<body>
  <!-- Bonsai Checkout JS -->
  <script type="text/javascript" src="https://ui.getbonsai.com/index.js"></script>
</body>

Step 3: Configure Bonsai Checkout

checkout.html
<!-- as defined in the previous step -->
<!-- <script type="text/javascript" src="https://ui.getbonsai.com/index.js"></script> -->
<script type="text/javascript">
  // Extract bonsai object from window
  var bonsai = window.__BONSAI__;

  function customOrderSuccessMessage({ email }) {
    return `Thank you! You will receive a confirmation email with your order details shortly. Your account has been created using ${email}.`;
  }

  // Initialize bonsai with configuration options
  bonsai.init({
    accountId: '<API_KEY_VALUE>',
    customInfoMessage: 'Custom message displayed on the cart page',
    bonsaiEvents: {
      version: 'v1',
      onBonsaiEvent: ({ tag, event, data }) => {
        switch (tag) {
          case 'order_completed':
            console.log('Order completed', event);
            break;
          case 'product_unavailable':
            console.log('Product unavailable', data);
            break;
          // ...
        }
      },
    },
    customOrderSuccessMessage,
  });
</script>

info

For more details on bonsaiEvents please refer to the Events page.

Checkout types

Bonsai Checkout supports 2 checkout types: Single product and Multi product. You can set it using the checkoutType (further details in step 3 section).

Single product

Bonsai UI can run in single product mode, which means that it will display a single product with no cart support. productId and variantId are required for this mode, and the application will automatically create a cart for you, containing the provided product. This cartId will be re-used for future checkouts, until the cart is deleted after successful checkout.

Multi product

Multi product mode is the default mode, and it supports multiple products and variants. It requires a cart ID, which you need to create using the Bonsai Carts API.

Configuration options

type Config = {
  /* REQUIRED: */

  /* Authenticates your account with Bonsai services */
  accountId: string;

  /* The type of checkout.
   *
   * - `single-product` - checkout for a single product with no cart support
   *    - `productId` - product ID
   *    - `variantId` - variant ID
   *
   * -  `multi-product` - checkout for multiple products, using regular cart
   *    - `cartId` - cart ID
   */
  checkoutType: 'single-product' | 'multi-product';

  /* single-product checkout options */
  productId: string;
  variantId: string;

  /* multi-product checkout options */
  cartId: string;

  /* OPTIONAL */

  /* Deprecated: Instead, please use onBonsaiEvent with "order_completed" tag. */
  onSuccess?: (order: Order) => void;
  /* Deprecated: Instead, please use onBonsaiEvent with "shipping_info_entered" tag. */
  onShippingSubmit?: (context: ShippingContext) => void;

  /* A callback that will be invoked when user submits payment information */
  bonsaiEvents?: {
    /* A version of the Bonsai events. This allows us to make breaking changes
     * to the events without breaking your integration. */
    version: 'v1';
    /* A callback that will be invoked when a Bonsai event has been emitted. */
    onBonsaiEvent: (event: BonsaiEvent) => void; // More details in "Events" page
  };

  /* A color for the button fill */
  buttonBackground?: string;
  /* A color for the button font color */
  buttonTextColor?: string;
  /* A custom google font override */
  font?: string;
  /* A custom message displayed on the cart page */
  customInfoMessage?: string;
  /* A custom message displayed on the order success page. `ShippingContext` data is provided as an argument
   * to the function, so you can get access to the ShippingContext information. If `null` is returned, the
   * default message will be displayed.
   */
  customOrderSuccessMessage?: (context: ShippingContext) => string | null;
  /* A custom link displayed on the order success page. If not provided, the link will not be displayed.
   * Requires an `href` value. If `text` not provided, the link will use a default text instead ("Go back").
   */
  customOrderSuccessLink?: { href: string; text?: string };
  /* If provided, the checkout header image will link to the provided URL */
  originUrl?: string;
  /* ID of the order provided to Bonsai by the party who placed the order - should be unique per order if passed. */
  externalOrderId?: string;
  /*
   * An array of allowed countries for checkout. If provided, the shipping form will be restricted to
   * these countries. Otherwise defaults to our supported countries.
   * Use ISO 3166-1 alpha-2 country codes (e.g., 'US' for United States, 'CA' for Canada).
   */
  allowedCountries?: ('CA' | 'US' | 'GB')[];
};

type ShippingContext = {
  cartId: string;
  shipping: {
    address: {
      address1: string;
      address2?: string;
      city: string;
      country: string;
      firstName: string;
      lastName: string;
      zip: string;
    };
    email: string;
    phone: string;
  };
};

Script data attributes

Data attribute	Value	Description	Required
`src`	`https://ui.getbonsai.com/index.js` or `https://staging-ui.getbonsai.com/index.js`	Bonsai Checkout Javascript URL	✅

Step 4: Create cart

In order to start the checkout process, you need to create a cart first. You can do this by using Bonsai Carts API

curl -L -X POST 'https://api.shopbonsai.ca/carts/v1/submit' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'API-Key: <API_KEY_VALUE>' \
--data-raw '{
  "products": [
    {
      "id": "clad6pg5z00eu012gfz7hfm92",
      "variantId": "M00679529706740",
      "quantity": 1
    }
  ]
}'

# result:
# {"data":{"id":"RANDOM_CART_ID"}}

info

You can find more information about how to create and update carts using the Bonsai Carts API here.

Step 5: Redirect to checkout

After you have created a cart, and obtained a cart id, you can redirect the user to the Checkout page.

You will need to add a bonsai query parameter to the Checkout page URL, with the cart id as its value.

Example

https://your.domain.com/checkout?bonsai=checkout_ID

Hosted

Coming soon...

Changelog

November 21, 2023
- Addition of ApplePay/GooglePay events
- Events extracted to separate page
November 14, 2023
- Additional BonsaiEvent types
November 6, 2023
- Added province to shipping_info_entered BonsaiEvent.
October 26, 2023
- Additional fields added to all BonsaiEvent types.
- onShippingSubmit and onSuccess callbacks are deprecated.
- bonsaiEvents supports the same functionality, and should be used instead.

Integrations

Embedded​

Query parameters​

Callbacks​

Step 1: Create a page​

Step 2: Add Bonsai Checkout dependencies​

Step 3: Configure Bonsai Checkout​

Checkout types​

Single product​

Multi product​

Configuration options​

Script data attributes​

Step 4: Create cart​

Step 5: Redirect to checkout​

Hosted​

Changelog​

Embedded

Query parameters

Callbacks

Step 1: Create a page

Step 2: Add Bonsai Checkout dependencies

Step 3: Configure Bonsai Checkout

Checkout types

Single product

Multi product

Configuration options

Script data attributes

Step 4: Create cart

Step 5: Redirect to checkout

Hosted

Changelog