Products

Read and manage product catalog data using client.products — list, get, create, update, delete, and count.

client.products gives your plugin full CRUD access to a merchant's product catalog.

Required Scopes

Operation	Required Scope
`list`, `get`, `count`	`read:products`
`create`, `update`, `delete`	`write:products`

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

HTTP Mapping

Method	HTTP Verb	Path
`list(params?)`	GET	`/products`
`get(id)`	GET	`/products/:id`
`create(data)`	POST	`/products`
`update(id, data)`	PATCH	`/products/:id`
`delete(id)`	DELETE	`/products/:id`
`count(status?)`	GET	`/products/count`

Methods

list

Retrieve a paginated list of products.

const { data, pagination } = await client.products.list({
  page: 1,
  per_page: 25,
  status: "active", // "active" | "inactive" | "draft"
});

console.log(data[0].name);
console.log(pagination.total);   // Total matching products
console.log(pagination.pages);   // Total pages

get

Retrieve a single product by its ID.

const product = await client.products.get("472819365047");

console.log(product.name);
console.log(product.price);
console.log(product.status);

create

Create a new product in the merchant's catalog.

const newProduct = await client.products.create({
  name: "Premium Plan — Annual",
  price: 299.99,
  status: "active",
  // Additional fields as defined by the API schema
});

console.log(newProduct.id); // ID assigned by the platform

update

Partially update an existing product. Only the fields you pass are changed.

const updated = await client.products.update("472819365047", {
  name: "Premium Plan — Annual (Updated)",
  price: 249.99,
});

console.log(updated.name);

delete

Permanently remove a product from the catalog. This action cannot be undone.

await client.products.delete("472819365047");

count

Get the total number of products, optionally filtered by status.

// Count all products
const total = await client.products.count();

// Count only active products
const active = await client.products.count("active");

console.log(`${active} active products out of ${total} total`);

Error Handling

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

try {
  const product = await client.products.get("999999999999");
} catch (error) {
  if (error instanceof NotFoundError) {
    // Product does not exist
    console.log(`Not found: ${error.resourceId}`);
  } else if (error instanceof AuthorizationError) {
    // Missing read:products scope
    console.log(`Missing scope: ${error.requiredScope}`);
  } else if (error instanceof ValidationError) {
    error.fieldErrors.forEach((e) => console.log(`${e.field}: ${e.message}`));
  } else {
    throw error;
  }
}

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

On this page