Catalogs and commerce
Manage a Number's catalog, products, collections, carts and orders, and send products in messages.
A catalog lists the products a business sells on WhatsApp. On a Linked Devices Number you manage the WhatsApp Business app catalog directly; on a Meta Cloud API Number you read the catalog linked to its WhatsApp Business Account and send its products in messages.
Catalog reads can target the connected account or another supported business ID. Changes apply to the connected WhatsApp Business app account.
Console availability#
The Console shows Catalogs only for teams with access. If the workspace is not in your navigation, use the API operations in this guide. Existing Catalog API access is unchanged.
Catalogs and products#
- Get business catalog to inspect products and pagination state.
- Create business catalog if the account has no catalog.
- Create business product or Update business product.
- Delete business product when it is no longer sold.
Updating a business product replaces the complete product. Read the current product and resend every optional value you want to keep. Omitted descriptions, sale prices, retailer IDs, URLs, videos, and compliance fields are removed.
Product request rules#
| Fields | Accepted input |
|---|---|
images[].url, images[].base64, images[].mediaUrl | Set exactly one source on each image. Zero sources or multiple sources on one image are rejected. |
| Image payload size | Each decoded base64 image or downloaded image accepts at most 16 MiB. |
images[].url | Use an HTTPS URL. |
images[].mediaUrl | Use an HTTPS URL on whatsapp.net, fbcdn.net, facebook.com, or their subdomains. |
price and currency | Omit both, or provide both. A product with price must include its three-letter uppercase currency code. |
salePrice | Provide only when price is present. Because price requires currency, a discounted product includes all three fields. |
videoUrls | Use HTTPS URLs on whatsapp.net, fbcdn.net, facebook.com, or their subdomains. |
Product price and salePrice values are digit strings scaled in thousandths of the selected currency. For example, "12500" represents 12.5 currency units (12500 / 1000). Currency codes must be consistent anywhere totals are calculated.
Collections#
Use List business collections and Get business collection for reads.
Create business collection, Update business collection, and Reorder business collections control collection membership and order.
Collection request rules#
| Operation | Accepted input |
|---|---|
| Create | Provide 1 through 100 unique product IDs. |
| Update | Provide a new name, at least one non-empty membership list, or both. Empty updates are rejected. Each product ID can appear in only one of the add or remove lists. |
| Reorder | Provide 1 through 100 moves. Each collection ID can appear in at most one move. |
Visibility, appeals, and carts#
Appeal reasons are trimmed, cannot be blank, and accept at most 4096 UTF-8 bytes.
Orders#
Get business order requires the order ID and encrypted order token from the incoming order message. Send the token only in the JSON request body; never place it in a URL, query parameter, or log. The token must be nonblank and accepts at most 8192 characters. Treat the returned currency and prices as one atomic order snapshot.
An incoming order or payment callback does not establish that money settled. Use your payment provider's verified settlement record as the authority for a paid state.
Catalogs linked to a Meta Cloud API account #
For Official API Numbers, List linked product catalogs reads the catalogs associated with the Number's WhatsApp Business Account. Use the WABA ID of a Number in your project and a credential with sessions:read. Meta controls which catalogs the connected account can see and returns its permission error if the account lacks access. Pass paging.cursors.after as after to read the next page; limit accepts 1 to 100 and defaults to 25.
List linked catalog products reads product IDs, retailer IDs, names, and availability from a catalog in that WABA's linked list. Pass the WABA ID and catalog ID, with sessions:read. When more products exist, the response includes paging.cursors.after; pass it as after to continue. The last page has no paging object. limit accepts 1–100 and defaults to 25. Meta controls which products the connected credential can read. This read does not prove that a product can be sent or that the account can transact.
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/$WABA_ID/product_catalogs?limit=25" \
-H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN"
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/$WABA_ID/product_catalogs/$CATALOG_ID/products?limit=25" \
-H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN"Send catalog products#
Use Send a message with an Official API Number, a credential with messages:write, and Meta access to its linked catalog. Set type to interactive and interactive.type to product for one item or product_list for sections of items. The catalog_id must appear in the Number's WABA catalog list. Polymorfa checks that association before dispatch; a missing grant or incomplete catalog read stops the send. Meta validates each product_retailer_id and remains the authority for product availability.
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/$PHONE_NUMBER_ID/messages" \
-H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "15551234567",
"type": "interactive",
"interactive": {
"type": "product",
"action": {
"catalog_id": "123456789012345",
"product_retailer_id": "YOUR_PRODUCT_SKU"
}
}
}'For product_list, add a text header and body, then set action.sections to 1–10 sections. Each section needs a product_items array with at least one item, and the message accepts at most 30 items across all sections; each item has a product_retailer_id. Give every section a title when sending multiple sections. For Hybrid sends, reconcile the operation status after an uncertain response and reuse the same idempotency key. Do not replay an uncertain send with a new key.
Get commerce settings and Update commerce settings expose the supported Meta-compatible settings for Official API Numbers. The catalog read does not create a catalog or link one to the WABA.