JavaScript API

The JavaScript API is a small collection of methods for programmatically controlling the Back in Stock widget. It is available on any page of a Shopify store with Back in Stock installed. Use it to build a custom sign-up experience - for example, an inline form on your product page instead of the standard popup.

Create a new notification

Syntax:

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

Returns a BIS.Promise  which passes the server response to all registered callbacks.

Example: create an email notification

BIS.create('toni@example.com', 123456, 987654)

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

Example: create an SMS notification

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

The phone number must be a string in E.164 format. SMS notifications must be set up on your account before using this feature.

Example: create an email notification and show the response message

BIS.create('toni@example.com', 123456, 987654).then(function(resp) {
  resp.status == 'OK' ? alert(resp.message) : alert(resp.status)
})

See "Server response" below for a description of the resp  object.

Example: create an email notification with optional attributes

BIS.create('toni@example.com', 123456, 987654, { accepts_marketing: true, quantity_required: 3 })

Optional attributes:

• accepts_marketing : if true , the customer's email address is passed to any configured mailing list integrations. Use this to offer a newsletter sign-up checkbox alongside the Back in Stock request.
• quantity_required : set the quantity required value for the notification. Learn more about the quantity required feature.
• phone_number : send an SMS notification instead of email (see above).

BIS.popup methods

BIS.popup.show([options])

Show the notification registration form. Only available on a store product page. The optional options  object accepts:

• variantId : the ID of the variant the variant dropdown should select by default.

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

BIS.popup.hide()

Hides the notification registration form.

BIS.Promise methods

BIS.Promise  provides a simple promise interface for handling code that runs after a network response.

resolved  - true  if the promise has completed, otherwise false .

then(callback)  - register a callback to fire when the promise (i.e. the request) resolves.

var promise = BIS.create('test@example.com', 123456, 987654)
promise.then(function(data) { alert('OK ' + data.message) })

Example: a custom form

In this example we streamline the customer experience by embedding the sign-up form directly in the product page. Instead of showing the popup form, the email address is read from the form and sent to Back in Stock 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 logic in the template to hide the 'Add to Cart' button when a product is sold out.

Start by adding the email field to your product template:

<label for="notify_email">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 read the email address and create a new Back in Stock notification. We also need the product and variant IDs - here we render them with Liquid, assuming a single-variant product. If your product has a variant dropdown, read the variant ID from the select  element instead.

We also give the customer feedback: the server response includes the success and error messages configured in your Language settings, so we can show those directly.

<script>
  document.getElementById('notify_button').addEventListener('click', function(e) {
    e.preventDefault();
    var email = document.getElementById('notify_email').value,
        productId = {{ product.id }},                 // rendered by Liquid
        variantId = {{ product.variants.first.id }};  // rendered by Liquid

    BIS.create(email, variantId, productId).then(function(data) {
      var msg = '';
      if (data.status == 'OK') {
        msg = data.message; // the success message
      } else {
        for (var k in data.errors) { // collect the error messages
          msg += k + ' ' + data.errors[k].join();
        }
      }
      alert(msg);
    });
  });
</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 are included.

A successful save returns status: "OK" :

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

An error has status: "Error"  and returns the error messages keyed by field:

{ "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 JavaScript API, email backinstock-support@useamp.com.