Meta / Facebook Developer Docs Mirror

Appearance

Mirrored from https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/single-product-messages

Product card carousel templates ​

Updated: Jun 18, 2026

Product card carousel templates allow you to send a single text message accompanied by a set of up to 10 product cards in a horizontally scrollable view:

WhatsApp Product Card Carousel message with body text and a scrollable product card showing Black Prince Echeveria, $9.99, and a View button

When a WhatsApp user taps the View button, they can view more information about the product, add the product to a shopping cart, and place an order, all without leaving the WhatsApp client experience. If instead you prefer to send the user to your website when they click the button, see Media Card Carousel Templates.

Product cards ​

Carousel templates support up to 10 product cards, composed of message body text, a product image, product title, product price, and a single View button or URL button. All cards defined on a template must have the same components.

Product card carousel diagram labeling message body text, product image, product title, product price, and View button across three succulent product cards

View buttons ​

When a WhatsApp user taps the button, the product details view appears, displaying product information pulled from your product catalog.

Product details view for Black Prince Echeveria, $9.99, with description, Message business, and Add to order request buttons

Users can then add the product to a cart and place an order.

Your cart view with 1 item, Black Prince Echeveria at $9.99, an estimated total of $9.99, and a Place order button

When a user submits the cart, a webhook will be triggered describing the order, and an order confirmation message will appear in the message thread.

WhatsApp message thread order confirmation reading Order via catalog, 1 item, $9.99 estimated total, with a View details button

Users who have placed an order can see the contents of the order by tapping the View details button.

Your sent cart view with 1 item, Black Prince Echeveria, $9.99, Quantity 1, and an estimated total of $9.99

URL buttons ​

To send users to your website, use URL buttons instead of View buttons. When a WhatsApp user taps a URL button to buy a product, the URL mapped to the button is loaded in the device's default web browser, which takes the user out of the WhatsApp client experience. URL button flows can be useful when you want to load the product in your mobile checkout page where users can add promo codes and find related products.

With URL button flows, order placement happens outside of the WhatsApp client, so WhatsApp does not trigger order webhooks for URL-button flows.

Catalogs ​

To use product card carousel templates, you must have an e-commerce product catalog, with inventory, connected to your WhatsApp Business account. See the Cloud API Commerce guide to learn more about connecting a catalog to your account.

Webhooks ​

If you send a carousel template composed of product cards that use a View button, when a customer adds one or more products to their cart and submits an order, an order messages webhook is triggered, describing the order.

Use the Message Templates API to create a product card carousel template.

Request syntax ​

Define only two product cards when you create the template. An approved template with two product cards can be used to send up to 10 cards in a template message.

curl -X POST "https://graph.facebook.com/v23.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '
{
    "name": "<TEMPLATE_NAME>",
    "language": "<TEMPLATE_LANGUAGE>",
    "category": "marketing",
    "components": [
      {
        "type": "body",
        "text": "<MESSAGE_BODY_TEXT>",
        "example": {
          "body_text": [
            [
              "<MESSAGE_BODY_TEXT_VARIABLE_EXAMPLE_1>",
              "<MESSAGE_BODY_TEXT_VARIABLE_EXAMPLE_2>"
            ]
          ]
        }
      },
      {
        "type": "carousel",
        "cards": [
          {
            "components": [
              {
                "type": "header",
                "format": "product"
              },
              {
                "type": "buttons",
                "buttons": [
                  {
                    "type": "spm",
                    "text": "View"
                  }
                  // OR, for a URL button, use the following instead:
                  // {
                  //   "type": "url",
                  //   "text": "<URL_BUTTON_LABEL_TEXT>",
                  //   "url": "<URL_BUTTON_URL>",
                  //   "example": [
                  //     "<URL_BUTTON_URL_VARIABLE_EXAMPLE>"
                  //   ]
                  // }
                ]
              }
            ]
          }
          // Add a second product card here, following the same structure as above
        ]
      }
    ]
  }'

Request parameters ​

PlaceholderDescriptionExample Value
<MESSAGE_BODY_TEXT> StringRequired. Message body text. Supports variables. Maximum 1024 characters.Rare succulents for sale! {​{1}​}, add these unique plants to your collection.
<MESSAGE_BODY_TEXT_VARIABLE_EXAMPLE> StringRequired if message body text string uses variables. Message body text example variable string(s). Number of strings must match the number of variable placeholders in the message body text string. If message body text uses a single variable, body_text value can be a string, otherwise it must be an array containing an array of strings.Pablo
<TEMPLATE_LANGUAGE> StringRequired. Template language and locale code.en_US
<TEMPLATE_NAME> StringRequired. Template name. Maximum 512 characters.carousel_template_product_cards_v1
<URL_BUTTON_LABEL_TEXT> StringRequired if using a URL button. URL button label text. 25 characters maximum.Buy now
<URL_BUTTON_URL> StringRequired if using a URL button. URL to be loaded in the device's default web browser when the WhatsApp user taps the button. Supports 1 variable. Variable placeholder must be appended to the end of the URL string. Maximum 2000 characters.https://www.luckyshrub.com/rare-succulents/{​{1}​}
<URL_BUTTON_URL_VARIABLE_EXAMPLE> StringRequired if URL button URL uses a variable. URL button URL example variable string. Maximum 2000 characters.BUDDHA

Example request ​

This example request creates a product card carousel template with a message body that uses a single variable and two product cards. Once approved, it can be used to send up to 10 product cards in a template message.

curl 'https://graph.facebook.com/v25.0/161311403722088/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "carousel_template_product_cards_v1",
  "language": "en_US",
  "category": "marketing",
  "components": [
    {
      "type": "body",
      "text": "Rare succulents for sale! {​{1}​}, add these unique plants to your collection. All three of these rare succulents are available for purchase on our website, and they come with a 100% satisfaction guarantee. Whether you're a seasoned succulent enthusiast or just starting your plant collection, these rare succulents are sure to impress. Shop now and add some unique and beautiful plants to your collection!",
      "example": {
        "body_text": "Pablo"
      }
    },
    {
      "type": "carousel",
      "cards": [
        {
          "components": [
            {
              "type": "header",
              "format": "product"
            },
            {
              "type": "buttons",
              "buttons": [
                {
                  "type": "spm",
                  "text": "View"
                }
              ]
            }
          ]
        },
        {
          "components": [
            {
              "type": "header",
              "format": "product"
            },
            {
              "type": "buttons",
              "buttons": [
                {
                  "type": "spm",
                  "text": "View"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}'

Request syntax ​

Use the Messages API to send an approved product card carousel template to a WhatsApp user.

curl -X POST "https://graph.facebook.com/v23.0/<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "<WHATSAPP_USER_PHONE_NUMBER>",
    "type": "template",
    "template": {
      "name": "<TEMPLATE_NAME>",
      "language": {
        "code": "<TEMPLATE_LANGUAGE>"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "<MESSAGE_BODY_TEXT_VARIABLE_1>" },
            { "type": "text", "text": "<MESSAGE_BODY_TEXT_VARIABLE_2>" }
          ]
        },
        {
          "type": "carousel",
          "cards": [
            {
              "card_index": 0,
              "components": [
                {
                  "type": "header",
                  "parameters": [
                    {
                      "type": "product",
                      "product": {
                        "product_retailer_id": "<PRODUCT_ID_1>",
                        "catalog_id": "<CATALOG_ID>"
                      }
                    }
                  ]
                }
                // Add additional components (e.g., buttons) here if your template defines them
              ]
            }
            // Add additional cards here, incrementing card_index for each
          ]
        }
      ]
    }
  }'

Request parameters ​

PlaceholderDescriptionExample Value
<CARD_INDEX> IntegerRequired. Zero-indexed order in which card should appear within the card carousel. 0 indicates first card, 1 indicates second card, etc.0
<CATALOG_ID> StringRequired. ID of connected ecommerce catalog⁠ containing the product.194836987003835
<MESSAGE_BODY_TEXT_VARIABLE> ObjectRequired if template message body text uses variables, otherwise omit. Object describing a message variable. If the template uses multiple variables, you must define an object for each variable. Supports text, currency, and date_time types. See Messages Parameters. There is no maximum character limit on this value, but it does count against the message body text limit of 1024 characters.{ "type":"text", "text": "Pablo" }
<PRODUCT_ID> StringRequired. Product ID.vrpj01fvwp
<TEMPLATE_LANGUAGE> StringRequired. Template language and locale code.en_US
<TEMPLATE_NAME> StringRequired. Template name. Maximum 512 characters.carousel_template_media_cards_v1
<WHATSAPP_USER_PHONE_NUMBER> StringRequired. WhatsApp user phone number.+16505551234

Example request ​

This example request sends an approved template named carousel_template_product_cards_v1. It supplies a single body text variable value (which the template requires) and three product cards. Each card identifies where it should appear in the carousel (card_index), as well as the product ID and catalog ID where the card's product details (such as title, description, and price) can be found.

curl 'https://graph.facebook.com/v25.0/179776755229976/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "template",
  "template": {
    "name": "carousel_template_product_cards_v1",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Pablo"
          }
        ]
      },
      {
        "type": "carousel",
        "cards": [
          {
            "card_index": 0,
            "components": [
              {
                "type": "header",
                "parameters": [
                  {
                    "type": "product",
                    "product": {
                      "product_retailer_id": "vrpj01fvwp",
                      "catalog_id": "194836987003835"
                    }
                  }
                ]
              }
            ]
          },
          {
            "card_index": 1,
            "components": [
              {
                "type": "header",
                "parameters": [
                  {
                    "type": "product",
                    "product": {
                      "product_retailer_id": "va2l5ioeat",
                      "catalog_id": "194836987003835"
                    }
                  }
                ]
              }
            ]
          },
          {
            "card_index": 2,
            "components": [
              {
                "type": "header",
                "parameters": [
                  {
                    "type": "product",
                    "product": {
                      "product_retailer_id": "sqpjv0mgde",
                      "catalog_id": "194836987003835"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}'

Unofficial mirror for reference/search purposes. All content originates from developers.facebook.com — see the source link at the top of each page. Machine-readable indexes: llms.txt · llms-full.txt · About

Content © Meta Platforms, Inc. · Built by Arjun Aditya