JavaScript API

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

Create a new notification

Syntax:

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

Returns a  BIS.Promise  which will pass the server response to all registered callbacks. This function is available on any page on a Shopify store with Back in Stock installed.

BIS.create('[email protected]', 123456, 987654)

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

BIS.create(null, 123456, 987654, { phone_number: '+15551234567' })

Creates a Back in Stock SMS notification request for the variant with ID 123456 and product ID 987654. SMS notifications must be setup before using this feature.

Phone number must be a string in E.164 format. See: What is E.164?

Example: create an email notification and show a response message

BIS.create('[email protected]', 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.

BIS.create('[email protected]', 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.

BIS.popup 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

BIS.popup.show()

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

hide()

Hides the notification registration form.

Example: 

BIS.popup.hide()

BIS.Promise methods

BIS.Promise  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('[email protected]', 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 [email protected].

HTTP Endpoint:

For the Back in Stock Endpoint HTTPs requests see: Back in Stock Endpoint