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
- 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."
- Commerce settings per phone number: whether the cart is on and whether the catalog is visible.
- Product messages you send inside a customer service window, or catalog templates you send outside it.
-
The
orderwebhook when a customer sends their cart. - 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_priceis 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 shows7.99in 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.
-
fromcan be missing. The webhook reference warns that "wa_idandfromare omitted when the user has adopted a username", and points you touser_id(incontacts) andfrom_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.
toMinorparses decimal strings into paise without floating point, because0.1 + 0.2is 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.insert({ wamid: msg.id, phone: msg.from ?? null, userId: msg.from_user_id ?? null, check });
if (created) return { orderId: created.id, duplicate: false, check };
const winner = await store.findByMessageId(msg.id);
if (!winner) throw new Error(`order ${msg.id} was rejected as a duplicate but can't be found`);
return { orderId: winner.id, duplicate: true };
};
The test for this runs two deliveries of the same order concurrently and checks there's one order, with both callers getting the same ID.
After the order: what WhatsApp leaves to you
Once the order is saved, the rest of checkout is yours to design. Meta's single-product docs suggest "requesting delivery info or giving payment options". A sequence that works:
- Confirm the order straight away, with the total from your price book and any problems ("one item is out of stock; we've left it out").
- Collect the address, ideally with a WhatsApp Flow form rather than free text.
- Take payment with a payment link or UPI QR from your payment provider. Indian businesses can also use checkout-button templates and WhatsApp Payments to take payment inside the chat.
- Send the order and shipping updates as utility templates.
Taxes are explicitly yours too: the Commerce Policy makes you "solely responsible for determining, collecting, withholding, reporting, and remitting all applicable taxes".
What WAPGROWAI does today, and what it doesn't
Our catalog checkout follows the sequence above: an order confirmation, then a choice of paying online or cash on delivery, an address form built as a WhatsApp Flow, and a payment link or QR from the business's own Razorpay or Creem account. Measured against this post:
-
We connect a catalog with
POST /{WABA_ID}/product_catalogs, and treat Meta's "already linked" error as success when the catalog is in fact linked to that account. - We send product messages from chatbot blocks: one product as a single-product message, more as a multi-product message.
- Orders are idempotent on the message ID, with a lookup first and a unique index behind it.
-
We take the order total from the webhook prices, multiplying
item_priceby quantity and using the first item's currency. That's the opposite of the price-book check above, and it's the change we'd make first. - Multi-product messages go out as one section of up to 30 products. Anything past 30 is cut, and there's no splitting into several messages.
- Every product send and every order fetches the catalog from Graph to map IDs to SKUs and names, without a cache, up to 1,000 products. A failed page ends the walk early and quietly, so a product past that point is dropped from product messages and saved without a name on orders.
- We don't touch commerce settings. Cart and catalog visibility stay whatever the business set in Meta's tools.
-
We ignore
referred_product. A product question shows up in the inbox as plain text, without the product the customer was looking at. -
We don't support usernames yet. An order from a customer without a
fromnumber can't be matched to a contact correctly. - We don't send catalog templates, and our marketing sends still go through Cloud API. The October 2027 cutoff applies to us as much as anyone.
Checklist
- Connect one catalog per WhatsApp account, and check
is_catalog_visiblebefore sharing catalog links. - Reference products by Content ID (
product_retailer_id), and check every ID exists before sending: a multi-product message drops unknown ones and still sends. - Split big product lists into several messages: 30 products and 24-character section titles (Meta's limits), plus 10 sections and 60-character headers (the template limits, applied to be safe).
- Leave out-of-stock products out of the message, not just out of the order.
- Plan catalog templates for the Marketing Messages API before October 13, 2027.
- Price orders from your own price book; report webhook price differences.
- Parse money into integer minor units.
- Make order intake idempotent with a unique index on the message ID.
- Show
referred_productnext to product questions in your inbox. - Store
from_user_idas well asfrom. - Confirm, collect the address, take payment and send updates yourself.
WAPGROWAI is built by DI Solutions, a custom software and AI development company. This series covers what we've learned building WAPGROWAI on the WhatsApp Cloud API. Related: routing quick-reply buttons to actions and WhatsApp usernames will break your phone-keyed contacts.
Top comments (0)