Updated on October 25, 2026
To use a catalog with the WhatsApp Business API, you add your products to a Meta catalog (through Commerce Manager or the Commerce API), connect that catalog to your WhatsApp Business Account and send interactive messages that display the items: the full catalog, a single product or up to 30 products grouped into sections. The customer browses, builds a cart inside WhatsApp and sends the order, which reaches your webhook as an order message.
This guide covers setup, the message formats with payload examples, order handling and the limits stated in the official documentation.
How catalog commerce works
Meta’s catalogs overview breaks the process into four stages:
- Inventory: products are uploaded to a Meta catalog with name, description, price, images and availability. Catalogs accept physical or digital goods and also services.
- Commerce settings: per phone number, you decide whether the cart is enabled and whether the storefront icon shows.
- Sharing: catalog, single-product, multi-product or carousel messages.
- Responses: questions and orders arrive through the messages webhook.
Step 1: create and connect the catalog
If the business already has a Meta catalog (used for ads or Instagram, for example), it can reuse it. If not, there are two options, according to Upload inventory:
- create it in Commerce Manager, manually, from a spreadsheet or a feed;
- create it through Meta’s Commerce API, which is handy when stock comes from an ERP or an ecommerce platform.
Then connect the catalog to the WhatsApp account in WhatsApp Manager, following Meta’s help article on connecting catalogs.
Two important rules:
- One catalog per WhatsApp account. The same catalog serves every phone number in that account.
- Automatic review. WhatsApp reviews items added to a connected catalog. Items that break the commerce policy are flagged, and appeals happen in Commerce Manager.
The field that ties everything together is the product SKU, which the API calls product_retailer_id and Commerce Manager labels Content ID. Use the same SKU as your own system so you don’t need a mapping table.
Step 2: cart and storefront per number
Commerce settings live on each number’s whatsapp_commerce_settings endpoint. Per Set commerce settings, the default is cart enabled and storefront hidden.
# Enable the cart and show the storefront icon
curl -X POST "https://graph.facebook.com/vXX.X/PHONE_NUMBER_ID/whatsapp_commerce_settings?is_cart_enabled=true&is_catalog_visible=true" \
-H "Authorization: Bearer TOKEN"| Setting | Default | Effect |
|---|---|---|
is_cart_enabled | true | Shows add-to-cart buttons in the chat, catalog and product details |
is_catalog_visible | false | Shows the storefront icon in the chat and the catalog preview on the business profile |
Note: if the storefront is hidden, wa.me catalog links and the View catalog button show an invalid link warning.
Step 3: pick the message format
| Format | What it shows | API type | Outside the 24-hour window |
|---|---|---|---|
| Catalog message | One product image, text and a View catalog button | catalog_message | Catalog template |
| Single product | One product with image, title, price and a View button | product | Single-product template |
| Multi-product | Up to 30 products in sections | product_list | Multi-product template (marketing category, up to 10 sections) |
| Product carousel | 2 to 10 horizontally scrollable product cards | carousel | Carousel template |
Interactive product messages need no prior approval, since they are built on the fly with current price and stock. But Meta states that single-product and multi-product messages cannot be sent as notifications: only within an existing chat thread, that is, inside the 24-hour customer service window. To start a conversation, use the matching template.
Single product
{
"messaging_product": "whatsapp",
"to": "15551234567",
"type": "interactive",
"interactive": {
"type": "product",
"body": { "text": "Here's the model you asked about." },
"footer": { "text": "Free shipping over $50" },
"action": {
"catalog_id": "CATALOG_ID",
"product_retailer_id": "SNEAKER-BLUE-10"
}
}
}Multi-product
For multi-product messages, a text header is required, and each section has a title and a list of SKUs.
{
"messaging_product": "whatsapp",
"to": "15551234567",
"type": "interactive",
"interactive": {
"type": "product_list",
"header": { "type": "text", "text": "Picked for you" },
"body": { "text": "A few items from the new collection." },
"action": {
"catalog_id": "CATALOG_ID",
"sections": [
{
"title": "Sneakers",
"product_items": [
{ "product_retailer_id": "SNEAKER-BLUE-10" },
{ "product_retailer_id": "SNEAKER-BLACK-10" }
]
},
{
"title": "Socks",
"product_items": [
{ "product_retailer_id": "SOCKS-3PACK" }
]
}
]
}
}
}If none of the SKUs exist in the catalog, the API returns an error and the message is not sent. If at least one exists, the message goes out, unmatched SKUs are dropped and you get an error asking for a catalog update. Validate the list against stock before sending.
Catalog message
{
"messaging_product": "whatsapp",
"to": "15551234567",
"type": "interactive",
"interactive": {
"type": "catalog_message",
"body": { "text": "Browse all products and place your order right here." },
"action": {
"name": "catalog_message",
"parameters": { "thumbnail_product_retailer_id": "SNEAKER-BLUE-10" }
}
}
}thumbnail_product_retailer_id sets the header image. Without it, WhatsApp uses the image of the first item in the catalog.
Step 4: receive the cart
When the customer sends the cart, an order message reaches your webhook, as described in the order messages webhook reference:
{
"from": "15551234567",
"id": "wamid.HBgL...",
"timestamp": "1761400000",
"type": "order",
"order": {
"catalog_id": "CATALOG_ID",
"text": "Can it arrive tomorrow?",
"product_items": [
{ "product_retailer_id": "SNEAKER-BLUE-10", "quantity": 1, "item_price": 89.9, "currency": "USD" },
{ "product_retailer_id": "SOCKS-3PACK", "quantity": 2, "item_price": 12.5, "currency": "USD" }
]
}
}What to do with it:
- Recalculate the total in your system from the SKU and current price. Don’t treat the webhook’s
item_priceas the billing truth without checking. - Reply in the same thread with the summary, shipping and payment options. The customer service window is open, because the order is a customer message.
- Store the message
idso you don’t process the same order twice if the webhook is retried.
If the customer taps Message business from a product, you get a text message with a context object showing which product they were viewing. Use it to answer without asking “which item?”.
For businesses in Brazil, Meta also documents a payments API with order_details and order_status messages, which let you collect payment inside the chat via PIX (Brazil’s instant payment system), boleto (a bank payment slip) or payment links.
Cart rules that affect customer service
According to the official documentation:
- there is one cart per chat thread and per device; it does not sync across the customer’s devices;
- the cart does not expire until it is sent; once sent, it can’t be edited and the customer has to send a new one;
- each item allows up to 99 units, with no limit on distinct items;
- the business cannot send a cart to the customer;
- if a product becomes unavailable, it is removed from the cart and the customer sees a notice that items were updated;
- with the Cloud API, the cart icon does not appear in the chat header, unlike the WhatsApp Business app.
For teams with several agents, this means an order only exists in your system once the order webhook arrives. The article on delivery and restaurants shows how to chain the order with status messages, and the one on cart recovery covers reminders.
Costs
Product messages follow the normal billing rules. Interactive messages sent inside the customer service window are service messages: each number gets 1,000 free delivered per month, and after that each message is charged. Catalog, product and multi-product templates are charged by template category; the multi-product template, for example, is always marketing. The order the customer sends is not charged.
How this works with Vectalk
With Vectalk, product messages use Meta’s payload on POST /api/messages: the Send Product / Catalog page has examples for single product (product), multi-product (product_list) and catalog message (catalog_message). Cart and storefront settings can be read and changed through the API itself, with is_cart_enabled and is_catalog_visible, on the Get and Update commerce settings endpoints, using an instance token. Orders reach your registered webhooks as order messages with catalog_id and product_items, per the webhooks documentation.
To get started, create your account at apps.vectalk.com.br/register. To send your first message from code, see how to send a message through the WhatsApp API.
Frequently asked questions
Can I use the same catalog as Instagram and my ads?
Yes. If the business already has a Meta catalog, the official guidance is to use it and connect it to the WhatsApp account.
How many products fit in a multi-product message?
Up to 30 products. In the multi-product template, they can be organized into up to 10 sections.
Can I send a product message to someone who hasn’t messaged me today?
Not as an interactive message: it can only be sent within an existing conversation. To start contact, use a catalog, single-product, multi-product or carousel template.
Can customers pay inside WhatsApp?
The cart sends the order, not the payment. For businesses in Brazil, Meta documents a payments API with PIX, boleto and payment links through order_details messages. Otherwise, reply to the order with your checkout link or payment details.
Do product messages need approval?
Interactive product messages don’t. Catalog and product templates go through the usual template review.
Official sources consulted on October 25, 2026: Catalogs overview, Upload inventory, Set commerce settings, Share products, Single-product messages, Multi-product messages, Multi-product template messages, Catalog messages, Product carousel messages, Receive responses, Order messages webhook, WhatsApp orders (Brazil), WhatsApp Business Platform pricing, Meta help: connect a catalog, Vectalk docs: Send Product / Catalog, Vectalk docs: commerce settings.