JavaScript API
STOQ provides a JavaScript API for custom integrations within your Shopify theme. This API is accessible through the window._RestockRocket
object when our app loads into your theme.
Available APIs
All pages
stoq:loaded
Product Page
openModal, openInlineForm, removeInlineForm, renderButtonForVariant, getSellingPlan
Collection, Home, and Custom Pages
openModal
All pages
marketId
stoq:loaded
Event triggered when STOQ's app embed is loaded on any page supported by the app. Pages supported: Product, Collection, Home, Search
window.addEventListener('stoq:loaded', (event) => {
const { pageType, enabled, settings } = event.detail;
if (pageType === 'product' && enabled) {
console.log('Stoq loaded on product page', settings);
// Handle product page customizations
}
});
openModal
openModal(productData, variantId, customerData)
Opens the 'Notify me' modal for a specific product. This is typically used for custom elements like quick add buttons.
Parameters:
productData (Object): Contains product information
variantId (String): ID of the specific variant
customerData (Object): Contains customer information (Optional)
Examples:
Opening modal on a collection page:
const addToCartBtn = document.getElementById('quick-add-btn');
addToCartBtn.addEventListener('click', () => {
const productData = { id: 1111, variants: [{ id: 2222, available: false }] };
const variantId = '41XX';
const customerData = {
shopify_customer_id: 9999,
email: '[email protected]',
phone: '8123999123', // phone number
country_code: '1', // country code
country: 'us' // 2 letter ISO country code
} // Optional
window._RestockRocket.openModal(productData, variantId, customerData);
// Alternative: Using Liquid objects directly in Javascript
// window._RestockRocket.openModal({{ product | json }}, '{{ product.selected_or_first_available_variant.id }}');
});
Opening modal on a product page:
const notifyMeBtn = document.getElementById('notify-me-btn');
notifyMeBtn.addEventListener('click', () => {
// Default: Opens modal for the current product, it automatically gets the
// product data and currently selected variant ID
window._RestockRocket.openModal();
});
openInlineForm
openInlineForm(productData, variantId, customerData, inlineFormContainer, inlineFormContainerInsertType)
Shows the 'Notify me' modal as an Embedded form for a specific product variant. Use this API to show the Embedded Sign up form in a specific location when an out of stock variant is selected.
Parameters:
productData (Object): Contains product information
variantId (String): ID of the specific variant
customerData (Object): Contains customer information (Optional)
inlineFormContainer: Selector for the container where you want to insert the form (Optional)
inlineFormContainerInsertType: How the form should be inserted into the container (Optional)
Notes:
inlineFormContainer can be passed down in the function call, or you can set it up in-app. Chat with Support to get access to the relevant settings.
inlineFormContainerInsertType can be one of: beforebegin, afterbegin, beforeend, afterend. The default is 'beforeend'.
Example:
const addToCartBtn = document.getElementById('quick-add-btn');
addToCartBtn.addEventListener('click', () => {
const productData = { id: 1111, variants: [{ id: 2222, available: false }] };
const variantId = '41XX';
const customerData = {
shopify_customer_id: 9999,
email: '[email protected]',
phone: '8123999123',
country_code: '1',
country: 'us'
};
// Basic usage
window._RestockRocket.openInlineForm(
productData,
variantId,
customerData,
'#my-custom-container', // CSS selector where form will be inserted
'afterend' // Where to insert relative to selector: 'beforebegin', 'afterbegin', 'beforeend', 'afterend'
);
// Alternative: Using Liquid objects directly
// window._RestockRocket.openInlineForm(
// {{ product | json }},
// '{{ product.selected_or_first_available_variant.id }}',
// null,
// '#my-custom-container'
// );
});
removeInlineForm
Removes the Embedded form rendered using openInlineForm. Use this API to remove the Embedded Form after a successful submission or when a different variant is selected.
Example:
window._RestockRocket.removeInlineForm();
renderButtonForVariant
renderButtonForVariant(variantId)
Sets up or removes the button for a specific variant on the page. Useful when your theme has a custom variant selector.
Parameters:
variantId (String): ID of the variant to render the button for.
Example:
const variantSelector = document.getElementById('variant-selector');
variantSelector.addEventListener('change', (event) => {
const selectedVariantId = event.target.value;
window._RestockRocket.renderButtonForVariant(selectedVariantId);
});
getSellingPlan
getSellingPlan(variantId)
Retrieves the selling plan object for a given variant if a preorder is set up.
Parameters:
variantId (String): ID of the variant to check for a selling plan.
Returns:
(Object): The selling plan object if found, or null if no preorder is set up for the variant.
Example:
const variantId = '41XX';
const sellingPlan = window._RestockRocket.getSellingPlan(variantId);
if (sellingPlan) {
console.log('Preorder selling planDetails:', sellingPlan);
} else {
console.log('No preorder set up for this variant');
}
Example Response:
{
shopify_selling_plan_group_id: 123456789,
shopify_selling_plan_id: 987654321,
enabled: true,
variant_ids: [11111, 22222, 33333, 44444],
name: "Preorder Offer",
billing_checkout_charge_amount: "100.0",
billing_checkout_charge_percentage: "10.0",
billing_checkout_charge_type: "percentage",
billing_description: null,
billing_title: "Full payment",
discount_text: "Save {{ discount }}",
enable_billing_widget: true,
inventory_provider: "stoq",
payment_type: "full",
preorder_badge_background_color: "#000000",
preorder_badge_enabled: true,
preorder_badge_text: null,
preorder_badge_text_color: "#FFFFFF",
preorder_button_description: "Note: This is a preorder. Items will ship based on the estimated delivery date.",
preorder_button_description_background_color: "#ffffff",
preorder_button_description_border_radius: 20,
preorder_button_description_quantity_limit_suffix: " units available for preorder",
preorder_button_description_shipping_text_prefix: "Shipping: ",
preorder_button_description_show_quantity_limit: true,
preorder_button_description_show_shipping: true,
preorder_button_description_text_color: "#000000",
preorder_button_text: "Preorder Now",
preorder_shipping_text: "Estimated shipping: {{ date }}",
pricing_amount: null,
pricing_percentage: null,
pricing_type: "no_discount",
quantity_limit_text: "{{ quantity }} stock left",
shipping_applies_to_all_products: true,
shipping_text: "Shipping date to be determined",
translations: { /* language translations object */ }
}
Integration Examples
Quick Add Button on Collection Page
<div data-gb-custom-block data-tag="for">
<div class="product-item">
<h2>{{ product.title }}</h2>
<button class="quick-add-btn"
data-product-data="{{ product | json }}"
data-variant-id="{{ product.selected_or_first_available_variant.id }}"
>
Quick Add
</button>
</div>
</div>
<script>
document.querySelectorAll('.quick-add-btn').forEach(button => {
button.addEventListener('click', function() {
const productData = this.getAttribute('data-product-data');
const variantId = this.getAttribute('data-variant-id');
window._RestockRocket.openModal(productData, variantId);
});
});
</script>
Notify Me Button on Product Page
<div data-gb-custom-block data-tag="if">
<button id="add-to-cart-button">Add to Cart</button>
<div data-gb-custom-block data-tag="else"></div>
<button id="notify-me-btn">Notify Me When Available</button>
</div>
<script>
const notifyMeBtn = document.getElementById('notify-me-btn');
<div data-gb-custom-block data-tag="if" data-0='false' data-1='false' data-2='false' data-3='false'>
notifyMeBtn.addEventListener('click', function() {
window._RestockRocket.openModal({{ product | json }}, '{{ product.selected_or_first_available_variant.id }}');
});
</div>
// For themes with variant selectors
document.addEventListener('variantChange', function(event) {
const variant = event.detail.variant;
window._RestockRocket.renderButtonForVariant(variant.id);
});
</script>
Custom Integration on Product Page
<div id="product-form" data-product-id="{{ product.id }}">
<select id="variant-selector">
{% for variant in product.variants %}
<option value="{{ variant.id }}" {% if variant == product.selected_or_first_available_variant %}selected="selected"{% endif %}>
{{ variant.title }}
</option>
{% endfor %}
</select>
<button id="add-to-cart-btn" {% unless product.selected_or_first_available_variant.available %}style="display: none;"{% endunless %}>
Add to Cart
</button>
<button id="notify-me-btn" {% if product.selected_or_first_available_variant.available %}style="display: none;"{% endif %}>
Notify Me
</button>
</div>
<script>
const productForm = document.getElementById('product-form');
const variantSelector = document.getElementById('variant-selector');
const addToCartBtn = document.getElementById('add-to-cart-btn');
const notifyMeBtn = document.getElementById('notify-me-btn');
function updateButtons(variantId) {
const selectedVariant = {{ product.variants | json }}
.find(variant => variant.id.toString() === variantId);
if (selectedVariant && selectedVariant.available) {
addToCartBtn.style.display = 'block';
notifyMeBtn.style.display = 'none';
} else {
addToCartBtn.style.display = 'none';
notifyMeBtn.style.display = 'block';
}
}
variantSelector.addEventListener('change', function() {
const selectedVariantId = this.value;
updateButtons(selectedVariantId);
window._RestockRocket.renderButtonForVariant(selectedVariantId);
});
notifyMeBtn.addEventListener('click', function() {
const productData = {{ product | json }};
const variantId = variantSelector.value;
window._RestockRocket.openModal(productData, variantId);
});
// Initial setup
updateButtons(variantSelector.value);
</script>
These examples demonstrate how to integrate RestockRocket's API with buttons using onclick handlers and Shopify Liquid markup. The Liquid examples show how to access product and variant data directly from Shopify, which can then be passed to the RestockRocket API.
Remember to adjust these examples to fit your specific theme structure and requirements.
marketId
This returns the market ID the store is being viewed as:
window._RestockRocketConfig.marketId
Last updated