WhatsApp's catalog features look like a shop: customers browse products in the chat, fill a cart and tap send. What arrives at your server is less like a shop. It's a webhook with SKUs, quantities and prices, no payment, no address and no stock check, and Meta's Commerce Policy is clear about who handles the rest: "We are not responsible for processing, paying for, or fulfilling any sales relating to your transactions."

This post covers the developer side of that: connecting a catalog, sending product messages that stay inside Meta's limits, and turning the order webhook into an order you can safely charge for. It's based on the catalog checkout we built into WAPGROWAI, including the parts we'd do differently.

The code is TypeScript, run with node --experimental-strip-types and 9 tests. Meta facts are from its developer docs as of November 2026.

How the pieces fit

  1. A Meta catalog, created in Commerce Manager or through the Commerce API, and connected to the WhatsApp account. Meta allows "one catalog per WhatsApp account hierarchy", and "the same catalog serves every phone number in that hierarchy."
  2. Commerce settings per phone number: whether the cart is on and whether the catalog is visible.
  3. Product messages you send inside a customer service window, or catalog templates you send outside it.
  4. The order webhook when a customer sends their cart.
  5. Everything after that (pricing, stock, address, payment, fulfilment) is yours.

Commerce settings: check the defaults

Two flags live on the phone number, and their defaults surprise people. Per Meta's commerce settings page, "By default, the shopping cart is enabled and the storefront icon is hidden":

# Read them curl "https://graph.facebook.com/<VERSION>/<PHONE_NUMBER_ID>/whatsapp_commerce_settings" \ -H "Authorization: Bearer $TOKEN" # {"data":[{"is_cart_enabled":true,"is_catalog_visible":false,"id":"..."}]} (fresh defaults) # Show the catalog curl -X POST "https://graph.facebook.com/<VERSION>/<PHONE_NUMBER_ID>/whatsapp_commerce_settings?is_catalog_visible=true" \ -H "Authorization: Bearer $TOKEN" 

The visibility flag matters more than it looks. With the catalog hidden, "wa.me links to your catalog, as well as the View catalog button … will display an Invalid catalog link warning when tapped." If a business shares a catalog link in an ad or on Instagram and nobody turned this on, every tap is an error.

Turning the cart off is a valid choice too, for businesses that only want to show products: "customers can see products and their details, but cart-related buttons do not appear in any view."

One difference from the WhatsApp Business app: "messages sent via the Cloud API currently do not display a shopping cart icon in the chat thread header."

Product messages and their limits

Inside the 24-hour customer service window, you can send interactive product messages with no template and no approval:

  • Single-product message (interactive.type: "product"): one item, a body, no header.
  • Multi-product message (interactive.type: "product_list"): "up to 30 products from your catalog, organized into sections". A text header is required, and section titles are required when there's more than one section, max 24 characters.
  • Catalog message: a button that opens the whole catalog.

Every product is referenced by product_retailer_id, which is the item's Content ID in Commerce Manager, not the Graph ID of the product. Matching is forgiving in a way that hides bugs. For a multi-product message, if at least one item matches, "The API drops items without a match", sends the rest, and reports an error asking for a catalog update. If nothing matches, nothing is sent. So a typo in one SKU doesn't fail the send: that product just doesn't appear, and the only sign is an error you have to be watching for.

Two more rules from Meta's multi-product messages page: these messages can't be sent as notifications ("They can only be sent as part of existing chat threads"), and customers on old app versions are told delivery failed because their WhatsApp is out of date, while you get a failure webhook.

Building messages that fit

A real catalog is bigger than 30 products. Rather than cutting a list at 30 and losing the rest, split it into as many messages as needed, keep categories together as sections, and leave out what isn't in stock:

// What your own system knows about a product: the source of truth for price and stock. export type Product = { retailerId: string; name: string; priceMinor: number; currency: string; inStock: boolean; category: string }; export type PriceBook = Map<string, Product>; // 30 products and 24-character section titles are documented for product_list. The 10-section // and 60-character header caps come from the MPM template docs, and 1,024 for the body is our // own cap; we apply all of them here to stay on the safe side. export const MPM_LIMITS = { products: 30, sections: 10, sectionTitle: 24, header: 60, body: 1024 }; type Section = { title: string; product_items: { product_retailer_id: string }[] }; export type ProductListMessage = { messaging_product: "whatsapp"; to: string; type: "interactive"; interactive: { type: "product_list"; header: { type: "text"; text: string }; body: { text: string }; action: { catalog_id: string; sections: Section[] }; }; }; const clip = (s: string, n: number) => (s.length <= n ? s : s.slice(0, n - 1) + "…"); // Group in-stock products by category into as many product_list messages as needed: // at most 30 products and 10 sections each, never splitting a category across a message // unless the category alone is bigger than a message. export const buildProductLists = ( to: string, catalogId: string, products: Product[], copy: { header: string; body: string }, ): ProductListMessage[] => { const byCategory = new Map<string, string[]>(); for (const p of products) { if (!p.inStock) continue; const list = byCategory.get(p.category) ?? []; list.push(p.retailerId); byCategory.set(p.category, list); } const messages: Section[][] = []; let current: Section[] = []; let count = 0; const flush = () => { if (current.length) messages.push(current); current = []; count = 0; }; for (const [category, ids] of byCategory) { for (let i = 0; i < ids.length; i += MPM_LIMITS.products) { const chunk = ids.slice(i, i + MPM_LIMITS.products); if (count + chunk.length > MPM_LIMITS.products || current.length === MPM_LIMITS.sections) flush(); current.push({ title: clip(category, MPM_LIMITS.sectionTitle), product_items: chunk.map((id) => ({ product_retailer_id: id })), }); count += chunk.length; } } flush(); return messages.map((sections, i) => ({ messaging_product: "whatsapp", to, type: "interactive", interactive: { type: "product_list", header: { type: "text", text: clip(messages.length > 1 ? `${copy.header} (${i + 1}/${messages.length})` : copy.header, MPM_LIMITS.header) }, body: { text: clip(copy.body, MPM_LIMITS.body) }, action: { catalog_id: catalogId, sections }, }, })); }; 

The interactive docs don't state a section cap; the multi-product template allows "up to 10 sections" and a 60-character header, so I apply those limits to interactive messages too. Messages that pass the stricter rules pass both.

When the catalog changes under a customer

A product message isn't a snapshot. Prices, titles and images update "as soon as the customer client learns about the change from the server", and when an item goes out of stock, "the product message now shows the item as unavailable." If the item is already in someone's cart, "the item will be removed from the cart" and the cart shows "One or more items in your cart have been updated".

That's helpful, but it only works if your catalog is current. If stock lives in your own system and syncs to Meta's catalog once a night, a customer can still add an item that sold out at lunchtime, and the order arrives anyway. That's one more reason the order check below runs against your own data, not against the catalog.

Meta also reviews catalog items automatically: "If a policy-violating item is added, the product is flagged", and businesses "can appeal for disapproved items directly in the Meta Commerce Manager." Meta doesn't document what a product message does with a flagged item, so after a big catalog upload, check Commerce Manager for rejections before you send a campaign that features them.

Product questions arrive as text

Not every customer orders. Many tap Message business on a product and ask a question. That arrives as an ordinary text message with the product attached in context (abbreviated):

{ "context": { "referred_product": { "catalog_id": "194836987003835", "product_retailer_id": "di9ozbzfi4" } }, "type": "text", "text": { "body": "Is this still available?" } } 

Look up product_retailer_id and show the product next to the question in your inbox. "Is this still available?" with no product attached is a question nobody on the team can answer quickly.

Outside the window: templates, and a 2027 deadline

To show products to someone who hasn't messaged you in the last 24 hours, you need a template: catalog, multi-product, single-product, product carousel, or in India a checkout-button template. All of them are marketing templates, which means marketing pricing, and one more thing worth planning for now.

Per Meta's Marketing Messages API overview, "Cloud API will stop supporting marketing messages on October 13, 2027", and from April 13, 2027 "any new Messaging account created on or after this date will not be able to send marketing messages via Cloud API." After the cutoff, "sending marketing messages on Cloud API will produce an error." Marketing templates, catalog ones included, move to the Marketing Messages API, which lists product catalog formats as supported. Service messages, including in-window product messages, stay on Cloud API.

If your product-template sending is wired directly to Cloud API's /messages, put the switch on your roadmap now.

The order webhook

When a customer sends their cart, you get a message of type: "order":

{ "from": "919820011223", "id": "wamid.HBgM...", "type": "order", "order": { "catalog_id": "1234567890", "text": "Need it by Friday", "product_items": [ { "product_retailer_id": "SKU-1", "quantity": 2, "item_price": 499, "currency": "INR" } ] } } 

Three things to know about it:

  • item_price is what the customer saw, not what you've agreed to charge. Meta's reference describes it as "Individual product price", types it as an integer and shows 7.99 in the example. It doesn't say it's locked to your catalog at the moment of the order. Your system is the source of truth for price and stock.
  • Customers can order up to 99 of each item, with no limit on distinct items. Validate quantities against what you can actually sell.
  • from can be missing. The webhook reference warns that "wa_id and from are omitted when the user has adopted a username", and points you to user_id (in contacts) and from_user_id (on the message). If your order table keys customers by phone number, that's a problem waiting for its first customer with a username.

Pricing the order from your own book

export type OrderWebhook = { catalog_id: string; text?: string; product_items: { product_retailer_id: string; quantity: number | string; item_price: number | string; currency: string }[]; }; export type OrderLine = { retailerId: string; name: string; quantity: number; unitMinor: number; currency: string }; export type OrderCheck = { lines: OrderLine[]; totalMinor: number; currency: string | null; problems: { retailerId: string; problem: "unknown_product" | "out_of_stock" | "price_changed" | "bad_quantity" | "currency_mismatch"; detail?: string }[]; }; // Decimal string or number → integer minor units, without floating-point drift. export const toMinor = (value: number | string, decimals = 2): number => { const [whole, frac = ""] = String(value).trim().split("."); if (!/^\d+$/.test(whole) || !/^\d*$/.test(frac)) return NaN; return Number(whole) * 10 ** decimals + Number((frac + "0".repeat(decimals)).slice(0, decimals)); }; // Price every line from your own price book. The webhook tells you what the customer saw; // your system decides what they pay. export const checkOrder = (order: OrderWebhook, book: PriceBook): OrderCheck => { const lines: OrderLine[] = []; const problems: OrderCheck["problems"] = []; const currencies = new Set<string>(); for (const item of order.product_items ?? []) { const id = item.product_retailer_id; const product = book.get(id); const quantity = Number(item.quantity); if (!product) { problems.push({ retailerId: id, problem: "unknown_product" }); continue; } if (!Number.isInteger(quantity) || quantity < 1) { problems.push({ retailerId: id, problem: "bad_quantity", detail: String(item.quantity) }); continue; } if (!product.inStock) problems.push({ retailerId: id, problem: "out_of_stock" }); if (item.currency !== product.currency) { problems.push({ retailerId: id, problem: "currency_mismatch", detail: `${item.currency} vs ${product.currency}` }); } else if (toMinor(item.item_price) !== product.priceMinor) { problems.push({ retailerId: id, problem: "price_changed", detail: `${item.item_price} → ${product.priceMinor / 100}` }); } currencies.add(product.currency); lines.push({ retailerId: id, name: product.name, quantity, unitMinor: product.priceMinor, currency: product.currency }); } const currency = currencies.size === 1 ? [...currencies][0] : null; const totalMinor = lines.reduce((sum, l) => sum + l.unitMinor * l.quantity, 0); return { lines, totalMinor, currency, problems }; }; 

The decisions in there:

  • Every line is priced from your price book. The webhook price is compared, and a difference is reported as price_changed, but the total uses your price. If a sale ended an hour ago, the customer sees the correct total before paying, not after.
  • Money is integers. toMinor parses decimal strings into paise without floating point, because 0.1 + 0.2 is not a price.
  • Problems are reported, not fixed silently. An unknown SKU, a stock-out or a bad quantity goes into problems, and the out-of-stock line stays in the order so a person can see what the customer wanted. Whether to drop it, substitute it or ask is a business decision, not a parser's.
  • One currency per order. A mixed-currency cart is reported, not summed.

Taking it exactly once

Meta retries webhooks, and retries can produce duplicate notifications. If your handler is slow, a retry can arrive while the first delivery is still being processed, and "look it up, then insert" isn't enough for that. The database's unique index on the message ID makes the decision:

export type OrderStore = { findByMessageId: (wamid: string) => Promise<{ id: string } | null>; // Insert with a unique index on wamid; return null when that index rejects the row. insert: (row: { wamid: string; phone: string | null; userId: string | null; check: OrderCheck }) => Promise<{ id: string } | null>; }; // Meta retries webhooks, so the same order can arrive twice, possibly while the first is // still being handled. The unique index decides; the lookup first saves work on a plain retry. export const takeOrder = async ( store: OrderStore, // `from` is omitted when the customer has adopted a WhatsApp username; keep `from_user_id` too. msg: { id: string; from?: string; from_user_id?: string; order: OrderWebhook }, book: PriceBook, ): Promise<{ orderId: string; duplicate: boolean; check?: OrderCheck }> => { const existing = await store.findByMessageId(msg.id); if (existing) return { orderId: existing.id, duplicate: true }; const check = checkOrder(msg.order, book); const created = await store.Source:https://dev.to/wapgrowai_org/selling-through-whatsapp-catalogs-with-the-cloud-api-product-messages-the-order-webhook-and-1pa6

Related posts