Custom shops

For a loyalty solution to be operational, you need three basic ingredients:

Step 1: Send order and customer data to Bubblehouse. (Estimated effort: 4–8 hours.)

Step 2: Set up a way for Bubblehouse to implement discounts on your store. (Estimated effort: 3–6 hours.)

Step 3: Display a loyalty program page to the user. (Estimated effort: 2–4 hours.)

Here’s a video that goes over all of these steps:

Are you on the right page?

• This page explains how to build a completely custom integration with Bubblehouse, which is appropriate for in-house ecommerce systems and for systems that we do not have first-party support for.

• If you’re running Shopify, BigCommerce, Magento, WooCommerce, we have a first-party support for your ecommerce system and will take care of most or all of these steps. A custom system running on Stripe, Salesforce, Copilot and many other similar ecommerce platforms may also benefit from first-party integrations that we have, depending on your specific needs. Please talk to us.

Step 1: Send order, customer and product data to Bubblehouse

You will normally use Orders API to send the data to us, which is what the rest of the section is going to talk about. Bubblehouse has a few more ways to pull order/customer data for more exotic configurations, like CSV uploads.

API calls: UpdateOrders4, UpdateCustomers3, and UpdateProducts3.

UpdateOrders4 allows you to send one or more orders and order updates to Bubblehouse. (We recommend limiting to 1000 orders at a time.) Whenever an order is placed, or there’s any update on the order (shipment, adjustment, partial refund, cancellation, etc), use this API to provide the latest version of the order to Bubblehouse.

You can include customer and product catalog data within the orders, and Bubblehouse will create or update the relevant objects on our side. So you only call UpdateOrders4 and have a fully operational loyalty program.

However, we recommend proactively sending customer updates and the full product catalog to Bubblehouse:

• Whenever a customer signs up or updates their account data (name, email, etc), call UpdateCustomers3 to provide the latest customer data to us.

• Whenever a product is added, updated or removed, or collections are added or modified, or product-collection memberships are adjusted, call UpdateProducts3 to provide the latest catalog data to us.

Up-to-date customer data allows us to give out welcome points and greet the customers by name on the loyalty program.

Up-to-date product catalog allows us to configure product/collection-specific rewards and promos.

We have no required customer data — we only require some way to identify a customer, so sending an ID or an email is sufficient. However, we recommend that you send the following customer data if available:

• customer ID (whatever your system uses as a stable unique identifier; we deal with strings, so does not need to be a number)
• email
• first and last name (to allow us to identify and greet customers)
• phone number (so that we know if a phone number is already known for this customer, and can propose it in Sign Up for SMS block, if you have one)
• birthday (so that we can display it in Provide Birthday block, if you have one)

But all of that is optional; we’re running some loyalty programs that only give us customer IDs.

Step 2: Set up a way for Bubblehouse to implement discounts on your store

Bubblehouse implements rewarding via two primary methods:

1. Discount codes. Almost every type of reward we support (point redemption, free products, referral rewards) involves a discount code.

2. External gift cards (e.g. Amazon gift cards)

We have a few ways discount codes can be integrated:

1. The preferred method is for you to implement a webhook called CreateDiscount4. We will call this hook in real time every time we need to set up a new discount code, i.e. when a customer is redeeming points, sending a referral, redeeming a free product, and similar.

2. If on-demand generation is impossible or undesirable, you can pregenerate a large number of single-use codes and import them to Bubblehouse via CSV.

3. If single-use codes cannot be arranged, you can pregenerate a small number of multi-use codes and have Bubblehouse rotate them.

4. In some cases, we allow you to pregenerate a code on your end and provide it to us — we support this for personal referral codes certain scenarios.

Step 3: Display a loyalty program page to the user

When it comes to displaying the loyalty program, you have two options.

1. We build the loyalty UI. Our design team works with you to define the look and feel of the program, then our configuration team implements it. You only need to create a page on your site and drop in an IFRAME and our script, and pass authentication data (the currently logged in customer) into the iframe. This normally requires 2–4 hours of development work on your end. About 95% of our clients choose this method.

2. You build the loyalty UI using our APIs like CustomerBalance3, LoggedOutBalance1, RedeemPoints1, RedeemOffer1, UpdateCustomerDetails1 and more. This is a big project that will take you several weeks to complete, and gives you the ultimate flexibility. Only about 5% of our clients choose this method.

The iframe looks and feels like a part of your site. You provide the header and footer, including navigation, and the page content comes from our iframe. It works great on mobile, scrolls with the page, and fits into your design theme.

You will find the example script and iframe tags in your API console. Watch this video for more details:

You will need to build a JWT authentication token and pass it in the query string of the iframe.

We have docs on authentication, but we recommend that you simply watch this video:

Our team will provide an iframe for your main loyalty page. Depending on your program and needs, we may also provide additional iframes — for example, a dedicated referral page and a block for your account page.

If you’d like to include the customer’s point balance (and/or tier) into your navigation bar, and for other very small pieces of UI where an iframe does not make sense, you can use CustomerBalance3 API to fetch and display the information you want. You can query it from the frontend or from the backend.