JavaScript API

JavaScript API

The JavaScript API is a simple collection of methods that can be used to create programmatically control the Back in Stock widget.

BIS methods

create(email, variantId, productId, [attributes])

Create a new Back in Stock notification. Returns a   BISPromise which will pass the server response to all registered callbacks. This method is available from any page on a Shopify store with Back in Stock installed.

Example: create a notification
BIS.create('toni@example.com', 123456, 987654)

Creates a Back in Stock notification request for the variant with id '123456' and product id '987654'.

Example: create a notification and show a response message
BIS.create('toni@example.com', 123456, 987654).then(function(resp) { resp.status == 'OK' ? alert(resp.msg) : alert(resp.status) });

Creates a Back in Stock notification request for the variant with id '123456' and product id '987654' and displays the success or failure in an alert. See Server response below for a description of the resp object

Example: create a notification including optional attributes
BIS.create('toni@example.com', 123456, 987654, { accepts_marketing: true, quantity_required: 3 });

Creates a Back in Stock notification request for the variant with id '123456' and product id '987654'. Includes two optional fields:

  • accepts_marketing: If true, the customer email address will be passed to any configured mailing list integrations. Use this to include a checkbox to allow customers to sign up to your newsletter at the same time a Back in Stock notification is created.
  • quantity_required:  Set the quantity required value for the Back in Stock notification. Learn more about the quantity required feature.

BISPopover methods

show([options])

Show the notification registration form. This method is only available on a store product page.

The options argument is optional. If included it should be an object containing the following option:

  • variantId: the id of  the variant the variants dropdown should select as default

Example
BISPopover.show() 

BISPopover.show({variantId: 1234}) // shows the form with variant 1234 selected as default

hide()

Hides the notification registration form.

Example: 
BISPopover.hide()

create(emailvariantId)  [DEPRECATED]

Create a new Back in Stock notification. Returns a  BISPromise which will pass the server response to all registered callbacks.
This method is deprecated and will not be supported in future. Please use the simpler BIS.create() method above.

Example: 
BISPopover.create('test@example.com', 1234)

BISPromise methods

BISPromise provides a simple promise interface. Similar to callbacks, it helps to write handle code that executes asynchronously such as methods that wait for a network response.

resolved

Returns  true if the promise has completed, otherwise false

then( callback)

Specify a callback to fire when the promise (ie. the request) is resolved.

Example:

promise = BIS.create('test@example.com', 1234);
promise.then(function(data) { alert('OK ' + data); });

Example: a custom form

These concepts are best illustrated with an example.

In this example we will streamline the user experience for the customer by embedding the form directly in the product page. Instead of showing the popup form the email address will be read from the form and sent to the Back in Stock server using the JavaScript API.

Note: This example doesn't handle the logic of when to show or hide the form. Most Shopify themes already have this logic in the template to hide the ‘Add to Cart’ button when a product is sold out.

Start by adding the email field to the  product.liquid template:

<label>Email me when available</label>
<input type="email" id="notify_email">
<button id="notify_button">Email when available</button>

When the customer clicks the button we will read the email address from the email field and submit create a new Back in Stock notification. Form simplicity we will assume jQuery is available to use.

When creating a notification we also need to specify the product variant. In this example we will assume the product only has on variant and will read the id using some Liquid templating. If we had a multi-variant dropdown we would read the variant id from the dropdown  select element.

<script>
  $('#notify_button').click(function(e) {
    e.preventDefault();
    var email = $('#notify_email').val(),
        productId = {{product.id}},  // rendered by Liquid
        variantId = {{product.variants.first.id}}; // rendered by Liquid
    BIS.create(email, variantId, productId); // create the notification
  })
</script>

One more thing is needed: feedback to the customer. We'll create a callback function to let the customer know if creating the notification succeeded. If it didn't we can show the error message, too.

We will create a function  notificationCallback and register it as a callback. The response from the server includes the success and error messages set by the store owner in Language settings which can be displayed to the customer.

<script>
  var notificationCallback = function(data) {
    var msg = '';
    if (data.status == 'OK') {
      msg = data.message; // just show the success message
    } else { // it was an error
      for (var k in data.errors) {  // collect all the error messages into a string
         msg += (k + " " + data.errors[k].join());
       }
    }
    alert(msg);
  }
  $('#notify_button').click(function(e) {
    e.preventDefault();
    var email = $('#notify_email').val(),
        productId = {{product.id}},  // rendered by Liquid
        variantId = {{product.variants.first.id}}; // rendered by Liquid
    BIS.create(email, variantId, productId).then(notificationCallback);
  })
</script>

Server response

BIS.create() passes the server response to the callback as a JSON object. Any custom success or error messages configured in the app will be included.

A successful save will return a response with  status: 'OK'.

{
  "status": "OK",
  "message": "Your notification has been registered."
}

An error will have  status: 'Error' and return an array of error messages.

{
  "status": "Error",
  "errors": { "email":["The email address you entered is invalid"] }
}

Need more help?

If you need further information or want to provide feedback on the Developer API please drop an email to support@backinstock.org.

Still need help? Contact Us Contact Us