Skip to main content
When the Stockful app embed is enabled, a lightweight JavaScript API is exposed at window.stockful. It provides methods to fetch live inventory data, with built-in caching. The JS bundle is under 2 KB and loads with defer - it won’t block page rendering.

​
Setup

The API is automatically available when the Stockful app embed is enabled in the theme editor (App embeds > Stockful). No additional setup is required.

​
Waiting for the API

The API dispatches a stockful:ready event on window once initialized: 
if (window.stockful) {
  // Already loaded
  useStockful();
} else {
  window.addEventListener("stockful:ready", useStockful);
}

function useStockful() {
  // window.stockful is now available
}

​
Methods

​
getVariant

Fetch inventory data for a single product variant. 
window.stockful.getVariant(variantId: number): Promise<VariantData | null>
Parameters:
  • variantId - Shopify numeric variant ID
Returns: VariantData object or null if not found. 
const data = await window.stockful.getVariant(44123456789);
if (data) {
  console.log(data.stockStatus);  // "in_stock"
  console.log(data.daysOfSupply); // 12
}

​
getProduct

Fetch aggregated inventory data for a product (across all variants). 
window.stockful.getProduct(productId: number): Promise<ProductData | null>
Parameters:
  • productId - Shopify numeric product ID
Returns: ProductData object or null if not found. 
const data = await window.stockful.getProduct(8012345678);
if (data) {
  console.log(data.totalSold30d);          // 342
  console.log(data.lowStockVariantCount);   // 2
}

​
getVariants

Fetch inventory data for multiple variants in a single request. 
window.stockful.getVariants(variantIds: number[]): Promise<VariantData[]>
Parameters:
  • variantIds - Array of Shopify numeric variant IDs (max 50)
Returns: Array of VariantData objects. Variants not found are omitted. 
const variants = await window.stockful.getVariants([44123456789, 44123456790]);
variants.forEach(v => {
  console.log(`Variant ${v.variantId}: ${v.stockStatus}`);
});

​
getLocationAvailability

Fetch per-location stock for a variant. This returns live data from Shopify. 
window.stockful.getLocationAvailability(variantId: number): Promise<LocationData[]>
Parameters:
  • variantId - Shopify numeric variant ID
Returns: Array of LocationData objects, filtered by the store’s visibility settings. 
const locations = await window.stockful.getLocationAvailability(44123456789);
locations.forEach(loc => {
  console.log(`${loc.name}: ${loc.available ?? loc.status}`);
});

​
Types

​
VariantData

interface VariantData {
  variantId: number;
  stockStatus: string;           // "in_stock" | "low_stock" | "out_of_stock"
  daysOfSupply: number | null;
  velocityTrend: string;         // "selling_fast" | "steady" | "slow"
  projectedStockout: string | null; // ISO 8601 date
  abcClass: string | null;       // "A" | "B" | "C"
  restockStatus: string;         // "pending" | "needed" | "none"
  soldLast30d: number;
}

​
ProductData

interface ProductData {
  productId: number;
  stockStatus: string;           // "in_stock" | "low_stock" | "out_of_stock"
  lowStockVariantCount: number;
  velocityTrend: string;         // "selling_fast" | "steady" | "slow"
  totalSold30d: number;
}

​
LocationData

interface LocationData {
  locationId: string;
  name: string;
  city: string | null;
  provinceCode: string | null;
  countryCode: string | null;
  available?: number;   // Present when store has "show quantities" enabled
  status?: string;      // "in_stock" | "out_of_stock" - present when quantities are hidden
}

​
Events

​
stockful:ready

Dispatched on window when the API has initialized. 
window.addEventListener("stockful:ready", () => {
  console.log("Stockful API ready");
});

​
Caching

All methods cache responses in memory for 30 seconds. The server also returns Cache-Control headers (30s for variant/product data, 60s for location data), so the browser may serve cached responses beyond the JS cache. There is no manual cache invalidation - after 30 seconds, the next call for the same data will make a fresh request.