Helium Documentation

Helium.js

There are a number of ways in which you can use the Helium.js API to further customize the shopping cart and checkout experience of your store for your customers.

Shopping Cart

The following methods are available to developers to interact with a user’s shopping cart.

Helium.show()
Displays the checkout form, don’t call this when the customer’s shopping cart is empty

Example: The code below will show the checkout form immediately when the page loads

$(document).ready(function(){ Helium.show(); })
Helium.hide()
Close the checkout form
Helium.refresh()
Refresh the cart, without having to hide and then re-open the cart. Useful when programmatically making changes to the user's shopping cart that you would like to take affect.

Example

Helium.cart.add('eggs');
Helium.refresh(); // now the cart will show that 'eggs' have been added
Helium.cart.get()
Returns an array of SKU’s representing the user’s shopping cart

Example

var products = Helium.cart.get();
if (products.length == 0){
  alert("Your cart is still empty!");
}
Helium.cart.add(sku[, quantity ])
Add an item to the user's cart
sku
String required
The unique identifier you chose for this item when you created it (either via the web console or the API. Make sure not to allow users to add products to their carts without having first added each item.
quantity
Number optional, defaults to 1
The quantity of this item to add to the cart
Helium.cart.remove(sku[, limit ])
If turned on, we will email you each time a new order is complete. This is obviously not recommended if you have large sales volumes as it will flood your inbox. To receive notifications upon completed orders, checkout webhooks.
sku
String required
A unique identifier you choose for this item
limit
Number optional, defaults to null
The limit of the number of times to remove this. For example, setting a limit of 1 would only remove an item from the cart once, and if the item exists multiple times, the others will remain.
Helium.cart.count(sku)
Returns the number of times that an item with a given SKU appears in the cart
sku
String required
The SKU for the item you are querying

Example

if (Helium.cart.count('donut') == 0){
  alert("Are you sure you don't want any donuts, Homer?");
}
Helium.cart.clear()
Clear all items from the user's cart.

Customer Tagging

The following methods are available to add attributes to a customer that can be used later for filtering orders. For example, if you are tracking customer referrals from various sources, you may "tag" each customer with the source from which they have been referred.

Helium.customer.attr(name[, value])
Get or set an attribute
name
String required
The name of the attribute.
value
String optional
The value of the attribute. If provided, sets the attribute value. If ommitted, returns the attribute value for this customer. To delete an attribute, set value to null.

Example: The code below demonstrates using the attr method.

Helium.customer.attr("referrer", "blog");  // sets referrer to "blog"
Helium.customer.attr("referrer");         // returns "blog"
Helium.customer.attr("referrer", null);   // deletes referrer attribute
Helium.customer.attr("referrer");         // returns undefined
Helium.customer.get()
Returns an object describing the tags that have been added to the customer.

Example: Demonstrates using the get method

Helium.customer.get()   // returns {}
Helium.customer.attr("referrer", "blog");
Helium.customer.attr("gender", "female");
Helium.customer.get();   // returns {referrer: "blog", gender: "female"}

Coupons

The following methods are available to developers to interact with a user’s shopping cart.

Helium.customer.get()
Displays the checkout form, don’t call this when the customer’s shopping cart is empty

Example: The code below will show the checkout form immediately when the page loads

$(document).ready(function(){ Helium.show(); })
Helium.customer.attr(name[, value])
Get or set an attribute
name
String required
A unique identifier you choose for this item
value
Number optional
The limit of the number of times to remove this. For example, setting a limit of 1 would only remove an item from the cart once, and if the item exists multiple times, the others will remain.

Events

There are a number of events you can listen for on the div.#Helium object. Currently, in order for these to be triggered, you must have jQuery installed on your page.

ready
Triggered when the page is ready. Use this where you would normally use $(document).ready for jQuery users (more on this here).

Example

  $('#Helium').on('ready', function(e){
    console.log('ready to buy');
  });
add-to-cart
Triggered when an item is added to the cart

Example

  $('#Helium').on('add-to-cart', function(e, sku){
    console.log('added '+ sku + ' to cart');
  });
remove-from-cart
Triggered when an item is removed from the cart

Example

  $('#Helium').on('remove-from-cart', function(e, sku){
    alert("Are you sure you don't want " + sku + "?");
  });
show-cart
Triggered when the cart appears
close-cart
Triggered when the cart is closed
order-success
Triggered when an order successfully completes

Example

  $('#Helium').on('order-success', function(e, order){
    alert("You bought " + order.items.length + ' things');
  });
order-error
Triggered when an order fails

Example

  $('#Helium').on('order-error', function(e, msg){
    console.log(msg.errors);
  });

Advanced Notes for jQuery Users

Helium.js includes its own namespaced version of jQuery which does not interfere with any other versions of jQuery that you may have on your website. However, especially when using jQuery plugins, there are a couple things to do to ensure that Helium.js and all jQuery/jQuery plugins work smoothly together.

Always place the Helium script tag as the last JavaScript file loaded
This is especially important if you are loading any jQuery plugins, as conditions can occur where a plugin is added to the wrong version of jQuery before Helium.js has relinquished the global $ variable name. This is why we say to place the Helium.js script tag immediately before the </head> tag.
Use the $('#Helium') ready event instead of $(document) ready
This also addressed some rare race conditions that may occur when using jQuery plugins. Thus, to be safe, please use the Helium ready event.

Example: The code below will show the checkout form immediately when the page loads

// Instead of this...
$(document).ready(function(){
  // do something
});

// Do this...
$('#Helium').on('ready', function(){
  // now do something
});

Use of this site and associated services acknowledges your acceptance of the GDPR / Terms of Service