Products

Overview

Products are the core of your catalog. Each product can have multiple variants (sizes, colors, materials), belong to categories, carry custom field data for industry-specific attributes, and include images, SEO metadata, and flexible pricing.

Products connect to inventory (stock levels per variant per location), orders (line items reference product and variant IDs), and your storefront (published products appear in your online store). Use tags and categories to organize your catalog and power filtered browsing.

List Products

Retrieve products with optional filters. Use status to find active or draft products, category_id to browse by category, or search to match against name, SKU, and description.

const whale = new WhaleClient("wk_live_...");

// List active products
const products = await whale.products.list({
  status: "active",
  limit: 25
});

// Filter by category
const apparel = await whale.products.list({
  category_id: "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
});

// Search products
const results = await whale.products.list({
  search: "ceramic mug",
  limit: 25,
  offset: 0
});

Create a Product

Create a product by specifying name, description, pricing, and optional fields like images, category, and SKU. New products default to draft status unless you explicitly set status: "active".

const product = await whale.products.create({
  name: "Ceramic Mug — Ocean Blue",
  description: "Hand-thrown ceramic mug with ocean blue glaze. Dishwasher safe.",
  price: 2400,
  sku: "MUG-OCEAN-001",
  images: [
    "https://cdn.example.com/mug-ocean-front.jpg",
    "https://cdn.example.com/mug-ocean-side.jpg"
  ],
  category_id: "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  status: "active"
});

// Response
{
  "object": "product",
  "id": "prod_550e8400-e29b-41d4-a716-446655440000",
  "name": "Ceramic Mug — Ocean Blue",
  "description": "Hand-thrown ceramic mug with ocean blue glaze. Dishwasher safe.",
  "price": 2400,
  "sku": "MUG-OCEAN-001",
  "status": "active",
  "category_id": "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "images": [
    "https://cdn.example.com/mug-ocean-front.jpg",
    "https://cdn.example.com/mug-ocean-side.jpg"
  ],
  "created_at": "2026-03-10T09:00:00.000Z"
}

Variants

Variants represent different options for a product — sizes, colors, materials, or any other axis. Each variant has its own SKU, price, and inventory tracking. Orders reference variant IDs so fulfillment knows exactly which item to pick.

// Create a variant
const variant = await whale.products.variations.create(
  "prod_550e8400-e29b-41d4-a716-446655440000",
  {
    name: "Large",
    sku: "MUG-OCEAN-LG",
    price: 2999,
    weight: 450,
    dimensions: { length: 12, width: 10, height: 14, unit: "cm" }
  }
);

// Response
{
  "object": "product_variation",
  "id": "var_9b8c7d6e-f5a4-3210-dcba-987654321000",
  "product_id": "prod_550e8400-e29b-41d4-a716-446655440000",
  "name": "Large",
  "sku": "MUG-OCEAN-LG",
  "price": 2999,
  "created_at": "2026-03-10T09:05:00.000Z"
}

// List variants for a product
const variants = await whale.products.variations.list(
  "prod_550e8400-e29b-41d4-a716-446655440000"
);

Categories

Categories organize your catalog into a hierarchy. Each category can have a parent, enabling nested structures like Apparel → T-Shirts → Graphic Tees. Assign products to categories for filtered browsing on your storefront and in the admin.

// List all categories
const categories = await whale.categories.list();

// Create a top-level category
const apparel = await whale.categories.create({
  name: "Apparel",
  description: "Clothing and wearable goods",
  slug: "apparel"
});

// Create a nested category
const tshirts = await whale.categories.create({
  name: "T-Shirts",
  parent_id: apparel.id,
  slug: "t-shirts"
});

// Response
{
  "object": "category",
  "id": "cat_7a2b3c4d-e5f6-7890-abcd-ef1234567890",
  "name": "T-Shirts",
  "parent_id": "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "slug": "t-shirts",
  "created_at": "2026-03-10T09:10:00.000Z"
}

Custom Fields

Custom fields let you attach structured, industry-specific data to products. Define field schemas with types (text, number, boolean, select, date) and validation rules, then populate them per product. Use custom fields for specifications, compliance data, or any attribute not covered by the default product schema.

// Define a custom field schema
const field = await whale.customFields.create({
  name: "Material",
  field_type: "select",
  options: ["Ceramic", "Glass", "Stainless Steel", "Bamboo"],
  required: true,
  applies_to: "products"
});

// Set field value on a product
await whale.products.update(
  "prod_550e8400-e29b-41d4-a716-446655440000",
  {
    custom_fields: {
      "material": "Ceramic",
      "dishwasher_safe": true,
      "capacity_ml": 350
    }
  }
);

Tags

Tags provide a flat, flexible labeling system for products. Unlike categories (hierarchical), tags are freeform and can be used for seasonal collections, promotions, internal flags, or any cross-cutting grouping. Each tag has a name and an optional color for visual identification in the admin.

// Create a tag
const tag = await whale.productTags.create({
  name: "Summer 2026",
  color: "#FF6B35"
});

// Response
{
  "object": "product_tag",
  "id": "tag_4d5e6f70-a1b2-3c4d-e5f6-789012345678",
  "name": "Summer 2026",
  "color": "#FF6B35",
  "created_at": "2026-03-10T09:15:00.000Z"
}

// Assign tags to a product
await whale.products.update(
  "prod_550e8400-e29b-41d4-a716-446655440000",
  {
    tag_ids: [
      "tag_4d5e6f70-a1b2-3c4d-e5f6-789012345678",
      "tag_8a9b0c1d-2e3f-4a5b-6c7d-890123456789"
    ]
  }
);

// List all tags
const tags = await whale.productTags.list();

API Reference