Inventory

Read and adjust product inventory levels using client.inventory — get current stock and apply quantity adjustments.

client.inventory lets your plugin read and adjust inventory levels for individual products. This is useful for plugins that sync stock with an external warehouse, POS system, or fulfilment provider.

Required Scopes

Operation	Required Scope
`get`	`read:inventory`
`adjust`	`write:inventory`

Declare scopes in your whatalo.app.ts manifest so they appear in the install permission screen.

HTTP Mapping

Method	HTTP Verb	Path
`get(productId)`	GET	`/products/:id/inventory`
`adjust(productId, data)`	PATCH	`/products/:id/inventory`

Methods

get

Retrieve the current inventory levels for a product, including per-variant inventory when variants exist.

const { data } = await client.inventory.get("758517075954");

console.log(data.product_id);      // "758517075954"
console.log(data.stock_quantity);   // Current stock quantity
console.log(data.sku);             // Stock-keeping unit identifier
console.log(data.track_inventory); // Whether inventory tracking is enabled
console.log(data.variants);        // Array of variant-level inventory

The response includes a variants array with per-variant inventory levels:

const { data } = await client.inventory.get("758517075954");

for (const variant of data.variants) {
  console.log(`${variant.variant_type}: ${variant.variant_value}`);
  console.log(`  Stock: ${variant.stock_quantity}`);
  console.log(`  Tracked: ${variant.track_inventory}`);
}

adjust

Apply a quantity delta to a product's inventory. Positive values increase stock; negative values decrease it. The reason field is a free-text string stored in the inventory audit log — use any reason that makes sense for your business logic.

// Decrease stock by 5 (e.g., after a bulk order)
await client.inventory.adjust("758517075954", {
  quantity: -5,
  reason: "Bulk order fulfilment",
});

// Increase stock by 100 (e.g., after a warehouse restock)
await client.inventory.adjust("758517075954", {
  quantity: 100,
  reason: "Warehouse restock — shipment #WH-20241015",
});

// Custom reason — use any string
await client.inventory.adjust("758517075954", {
  quantity: -2,
  reason: "Promotional giveaway — Instagram campaign",
});

The reason field accepts any non-empty string. Common values include restock, correction, damaged, received, returned, but you can use any reason that fits your workflow.

Sync Pattern

A common pattern for inventory sync plugins:

import { WhataloClient } from "@whatalo/plugin-sdk";

const client = new WhataloClient({ apiKey: process.env.WHATALO_API_KEY! });

async function syncInventoryFromWarehouse(
  productId: string,
  warehouseQuantity: number
): Promise<void> {
  // 1. Read current stock on the store side
  const { data } = await client.inventory.get(productId);

  // 2. Calculate the delta
  const delta = warehouseQuantity - data.stock_quantity;

  if (delta === 0) {
    return; // Already in sync, nothing to do
  }

  // 3. Apply the adjustment
  await client.inventory.adjust(productId, {
    quantity: delta,
    reason: `Warehouse sync — warehouse qty: ${warehouseQuantity}`,
  });

  console.log(
    `Adjusted ${productId} by ${delta > 0 ? "+" : ""}${delta} units`
  );
}

Error Handling

import { NotFoundError, ValidationError } from "@whatalo/plugin-sdk";

try {
  await client.inventory.adjust("999999999999", {
    quantity: -10,
    reason: "test",
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    // Product does not exist
    console.log(`Product not found: ${error.resourceId}`);
  } else if (error instanceof ValidationError) {
    // e.g., inventory tracking not enabled, or adjustment would push
    // quantity below zero and the store disallows negative stock
    error.fieldErrors.forEach((e) => console.log(`${e.field}: ${e.message}`));
  } else {
    throw error;
  }
}

See Errors & Rate Limits for the full error class reference.