> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stockful.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer API

> window.stockful JavaScript API reference

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:

```javascript theme={null}
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.

```typescript theme={null}
window.stockful.getVariant(variantId: number): Promise<VariantData | null>
```

**Parameters:**

* `variantId` - Shopify numeric variant ID

**Returns:** `VariantData` object or `null` if not found.

```javascript theme={null}
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).

```typescript theme={null}
window.stockful.getProduct(productId: number): Promise<ProductData | null>
```

**Parameters:**

* `productId` - Shopify numeric product ID

**Returns:** `ProductData` object or `null` if not found.

```javascript theme={null}
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.

```typescript theme={null}
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.

```javascript theme={null}
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.

```typescript theme={null}
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.

```javascript theme={null}
const locations = await window.stockful.getLocationAvailability(44123456789);
locations.forEach(loc => {
  console.log(`${loc.name}: ${loc.available ?? loc.status}`);
});
```

## Types

### VariantData

```typescript theme={null}
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

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

### LocationData

```typescript theme={null}
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.

```javascript theme={null}
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.