The JavaScript API is a simple collection of methods that can be used to create programmatically control the Back in Stock widget.
Create a new Back in Stock notification
SI.create(email, variantId, productId, [attributes])
Returns a SIPromise 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 - Restock Alerts app installed.
Example: create an email notification
SI.create('[email protected]', 123456, 987654);Creates a Back in Stock email notification request for the variant with ID 123456 and product ID 987654.
Example: create a SMS notification
SI.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.
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
SI.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.
Example: create an email notification including optional attributes.
SI.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.
SIPopover 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
SIPopover.show()
SIPopover.show({variantId: 1234}) // shows the form with variant 1234 selected as defaulthide()
Hides the notification registration form.
Example:
SIPopover.hide()
create(email, variantId) [DEPRECATED]
Create a new Back in Stock notification. Returns a SIPromise 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 SI.create() method above.
Example:
SIPopover.create('[email protected]', 1234)
SIPromise methods
SIPromise
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 = SI.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 SI.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 SI.create(email, variantId, productId).then(notificationCallback); })</script>Server response
SI.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 contact us.