API reference

Commerce & Catalogs

Manage product catalogs, create and update catalog inventory, configure WhatsApp commerce settings, and send interactive shopping messages.

The WhatsApp Cloud API commerce suite consists of three focused modules:

whatsapp.catalogs — List and inspect Meta product catalogs and send product messages.
whatsapp.products — Create, list, update, and delete products within a catalog.
whatsapp.commerceSettings — Toggle catalog visibility and the in-chat shopping cart.

whatsapp.catalogs

Manage Meta product catalogs attached to your Meta Business Manager and send interactive catalog messages.

list

whatsapp.catalogs.list(): Promise<WhatsappResponse<PaginatedResult<WhatsappCatalog>>>

Lists catalogs owned by the configured Meta Business Manager account. Requires businessId (your Meta Business Manager ID, not the WABA ID) in the client constructor.

catalogs.ts

const { data, error } = await whatsapp.catalogs.list();

if (error) {
  console.error("Failed to list catalogs:", error.message);
} else {
  data.items.forEach((c) => {
    console.log(c.id, c.name, c.product_count, c.vertical);
  });
}

get

whatsapp.catalogs.get(catalogId: string): Promise<WhatsappResponse<WhatsappCatalog>>

Fetches metadata for a specific catalog by ID. Works with a known catalogId even if businessId is omitted in the config.

const { data: catalog, error } = await whatsapp.catalogs.get("1234567890");
if (catalog) {
  console.log(catalog.name, catalog.product_count);
}

listConnectedToWaba

whatsapp.catalogs.listConnectedToWaba(businessAccountId: string): Promise<WhatsappResponse<{ data: WhatsappCatalog[] }>>

Checks which catalog(s) are connected to your WhatsApp Business Account (WABA) for sending product messages.

const { data } = await whatsapp.catalogs.listConnectedToWaba(process.env.WA_WABA_ID!);
console.log("Connected catalogs:", data?.data);

Catalog message sending helpers

whatsapp.catalogs provides convenient delegates to the messages module for sending products to customers:

send-products.ts

// 1. Send a single product message
await whatsapp.catalogs.sendProduct("15551234567", {
  catalogId: "1234567890",
  productRetailerId: "SKU-1001",
  body: "Check out our latest espresso machine!",
  footer: "Free shipping available",
});

// 2. Send a multi-product list message (up to 30 products across 10 sections)
await whatsapp.catalogs.sendProductList("15551234567", {
  catalogId: "1234567890",
  header: "Summer Menu",
  body: "Select an item to view details or add to your cart:",
  footer: "In stock now",
  sections: [
    {
      title: "Hot Drinks",
      productRetailerIds: ["COFFEE-LATTE", "COFFEE-CAPPUCCINO"],
    },
    {
      title: "Pastries",
      productRetailerIds: ["PASTRY-CROISSANT", "PASTRY-MUFFIN"],
    },
  ],
});

// 3. Send entire catalog view message
await whatsapp.catalogs.sendCatalog("15551234567", {
  body: "Explore our complete store catalog:",
  footer: "Tap View catalog below",
  thumbnailProductRetailerId: "COFFEE-LATTE", // optional thumbnail
});

// 4. Send a swipeable product carousel (2 to 10 products)
await whatsapp.catalogs.sendProductCarousel("15551234567", {
  body: "Featured products on sale this week:",
  cards: [
    { catalogId: "1234567890", productRetailerId: "SKU-1001" },
    { catalogId: "1234567890", productRetailerId: "SKU-1002" },
    { catalogId: "1234567890", productRetailerId: "SKU-1003" },
  ],
});

whatsapp.products

Manage the product items inside a Meta catalog directly via the Graph API.

list

whatsapp.products.list(catalogId: string, params?: ListProductsParams): Promise<WhatsappResponse<PaginatedResult<WhatsappProduct>>>

const { data: products, error } = await whatsapp.products.list("1234567890", {
  limit: 50,
});

if (products) {
  products.items.forEach((p) => {
    console.log(p.retailer_id, p.name, p.price, p.currency, p.availability);
  });
}

get

whatsapp.products.get(productId: string): Promise<WhatsappResponse<WhatsappProduct>>

const { data: product } = await whatsapp.products.get("prod_987654");
console.log(product?.name, product?.price, product?.availability);

create

whatsapp.products.create(catalogId: string, input: CreateProductInput): Promise<WhatsappResponse<{ id: string }>>

create-product.ts

const { data, error } = await whatsapp.products.create("1234567890", {
  retailerId: "SKU-1004",
  name: "Ceramic Coffee Mug (12oz)",
  description: "Handcrafted ceramic mug with heat-resistant handle.",
  price: 1999, // in minor currency units (e.g. $19.99 = 1999 cents)
  currency: "USD",
  imageUrl: "https://example.com/images/mug-12oz.jpg",
  url: "https://example.com/products/ceramic-mug",
  availability: "in stock",
  condition: "new",
  brand: "ArtisanCraft",
  category: "Home & Garden > Kitchen & Dining > Tableware > Drinkware > Mugs",
});

if (error) console.error("Error creating product:", error.message);
else console.log("Created product ID:", data.id);

update

whatsapp.products.update(productId: string, patch: UpdateProductInput): Promise<WhatsappResponse<{ success: boolean }>>

await whatsapp.products.update("prod_987654", {
  price: 1799,
  availability: "in stock",
});

delete

whatsapp.products.delete(productId: string): Promise<WhatsappResponse<{ success: boolean }>>

const { data } = await whatsapp.products.delete("prod_987654");
console.log("Deleted:", data?.success);

whatsapp.commerceSettings

Check and update the commerce configuration for your WhatsApp phone number.

get

whatsapp.commerceSettings.get(opts?: { phoneNumberId?: string }): Promise<WhatsappResponse<CommerceSettings>>

const { data: settings } = await whatsapp.commerceSettings.get();
console.log("Catalog visible:", settings?.is_catalog_visible);
console.log("Cart enabled:", settings?.is_cart_enabled);

update

whatsapp.commerceSettings.update(input: UpdateCommerceSettingsInput, opts?: { phoneNumberId?: string }): Promise<WhatsappResponse<{ success: boolean }>>

await whatsapp.commerceSettings.update({
  isCatalogVisible: true,
  isCartEnabled: true,
});

Type reference

Parameter	Type	Description
retailerId*	string	Your SKU or product identifier. Must match productRetailerId when sending messages.
price*	number	Price in the smallest currency unit (e.g. cents: 1999 for $19.99).
availability	"in stock" \| "out of stock" \| "preorder" \| "available for order" \| "discontinued"	Inventory status for the product.
condition	"new" \| "refurbished" \| "used"	Condition of the item.
isCatalogVisible	boolean	Controls whether the catalog icon appears on your WhatsApp Business profile.
isCartEnabled	boolean	Controls whether customers can add products to an in-chat cart and submit order messages.