Stoq API Documentation

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

Page Type	Available APIs
Product Page	openModal, renderButtonForVariant, getSellingPlan
Collection, Home, and Custom Pages	openModal

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: 'john.doe@example.com',
	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();
});

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);
});

Integration Examples

Quick Add Button on Collection Page

{% for product in collection.products %}
  <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>
{% endfor %}

<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

{% if product.available %}
  <button id="add-to-cart-button">Add to Cart</button>
{% else %}
  <button id="notify-me-btn">Notify Me When Available</button>
{% endif %}

<script>
const notifyMeBtn = document.getElementById('notify-me-btn');

{% if product.available == false %}
  notifyMeBtn.addEventListener('click', function() {
    window._RestockRocket.openModal({{ product | json }}, '{{ product.selected_or_first_available_variant.id }}');
  });
{% endif %}

// 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

{% assign current_variant = product.selected_or_first_available_variant %}

<div id="product-form" data-product-id="{{ product.id }}">
  <select id="variant-selector">
    {% for variant in product.variants %}
      <option value="{{ variant.id }}" {% if variant == current_variant %}selected="selected"{% endif %}>
        {{ variant.title }}
      </option>
    {% endfor %}
  </select>
  
  <button id="add-to-cart-btn" {% unless current_variant.available %}style="display: none;"{% endunless %}>
    Add to Cart
  </button>
  
  <button id="notify-me-btn" {% if current_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>

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');
}

Preorder selling planDetails:
{
  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 */ }
}

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.

Updated on: 27/11/2024