WhatsApp Business Platform
WhatsApp Business Platform
Resources

Coupon code templates

Updated: Dec 3, 2025
Coupon code templates are marketing templates that display a single copy code button. When tapped, the code is copied to the customer’s clipboard.

Limitations

  • Coupon code templates are currently not supported by the WhatsApp web client.
  • Copy code button text cannot be customized.
  • Templates are limited to one copy code button.

Creating coupon code templates

Use the POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates endpoint to create coupon code templates.

Request syntax

curl 'https://graph.facebook.com/<API_VERSION>/<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-d '
{
  "name": "<TEMPLATE_NAME>",
  "language": "<TEMPLATE_LANGUAGE>",
  "category": "marketing",
  "components": [

    <!-- Only if using a header component -->
    {
      "type": "header",
      "format": "text",
      "text": "<HEADER_TEXT>"
    },

    {
      "type": "body",
      "text": "<BODY_TEXT>",

      <!-- Only include if body text includes one or more parameters -->
      "example": {
        "body_text": [
          [
            "<BODY_PARAMETER_EXAMPLE_VALUE>"
            <!-- Additional examples values would follow, if using multiple body parameters -->
          ]
        ]
      }
    },
    {
      "type": "buttons",
      "buttons": [

        <!-- Only if using a quick-reply button -->
        {
          "type": "quick_reply",
          "text": "<QUICK_REPLY_BUTTON_LABEL_TEXT>"
        },

        {
          "type": "copy_code",
          "example": "<COPY_CODE_BUTTON_EXAMPLE_CODE>"
        }
      ]
    }
  ]
}'

Request parameters

Placeholder Description Example Value
<ACCESS_TOKEN>
String
Required.
Access token.
EAAAN...
<API_VERSION>
String
Optional.
API version. If omitted, defaults to the newest API version available to your app.
v23.0
<BODY_PARAMETER_EXAMPLE_VALUE>
String
Required if using a body component string that includes one or more parameters.
Example parameter value. You must supply an example for each parameter defined in your body component string.
0itCfer5xDB14SHWLACB
<BODY_TEXT>
String
Required.
Template body text. Variables are supported.
Maximum 1024 characters.
Shop now through the end of December and use the one-time use code {{1}} to get {{2}} off of your entire order!
<COPY_CODE_BUTTON_EXAMPLE_CODE>
String
Required.
Code to be copied to device clipboard when tapped.
Maximum 20 characters.
fLBponPDsqF0KQThzkrf
<HEADER_TEXT>
String
Required if using a text header component.
Header text.
Maximum 60 characters.
Our Winter Sale is on!
<QUICK_REPLY_BUTTON_LABEL_TEXT>
Required if using a quick-reply button.
Button label text. Maximum 25 characters. Alphanumeric characters only.
Unsubscribe
<TEMPLATE_LANGUAGE>
String
Required.
Template language code.
en_US
<TEMPLATE_NAME>
String
Required.
Template name. Must be unique, unless existing templates with the same name have a different template language.
Maximum 512 characters. Lowercase, alphanumeric characters and underscores only.
coupon_code_onetime_winter_2025
<WHATSAPP_BUSINESS_ACCOUNT_ID>
String
Required.
WhatsApp Business Account ID.
102290129340398

Response syntax

Upon success:
{
  "id": "<TEMPLATE_ID>",
  "status": "<TEMPLATE_STATUS>",
  "category": "<TEMPLATE_CATEGORY>"
}

Response parameters

Placeholder Description Example value
<TEMPLATE_CATEGORY>
MARKETING
<TEMPLATE_ID>
Template ID.
1627019861106475
<TEMPLATE_STATUS>
PENDING

Example request

curl 'https://graph.facebook.com/v25.0/102290129340398/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "coupon_code_onetime_winter_2025",
  "language": "en_US",
  "category": "marketing",
  "components": [
    {
      "type": "header",
      "format": "text",
      "text": "Our Winter Sale is on!"
    },
    {
      "type": "BODY",
      "text": "Shop now through the end of December and use the one-time use code {{1}} to get {{2}} off of your entire order!",
      "example": {
        "body_text": [
          [
            "fLBponPDsqF0KQThzkrf",
            "30%"
          ]
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe"
        },
        {
          "type": "COPY_CODE",
          "example": "fLBponPDsqF0KQThzkrf"
        }
      ]
    }
  ]
}'

Example response

{
  "category" : "MARKETING",
  "id" : "1924084211297547",
  "status" : "PENDING"
}

Sending coupon code templates

Request syntax

Use the POST /<BUSINESS_PHONE_NUMBER_ID>/messages endpoint to send an approved coupon template in a template message.
curl -X POST "https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/messages" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '
{
    "messaging_product": "whatsapp",
    "to": "<USER_PHONE_NUMBDER>",
    "type": "template",
    "template": {
      "name": "<TEMPLATE_NAME>",
      "language": {
        "code": "<TEMPLATE_LANGUAGE>"
      },
      "components": [
        {
          "type": "button",
          "sub_type": "copy_code",
          "index": <BUTTON_INDEX>,
          "parameters": [
            {
              "type": "coupon_code",
              "coupon_code": "<COUPON_CODE>"
            }
          ]
        }
        <!-- Additional components would follow, if templates requires them -->
      ]
    }
  }'

Request parameters

Placeholder Description Example Value
<ACCESS_TOKEN>
String
Required.
Access token.
EAAAN...
<API_VERSION>
String
Optional.
API version. If omitted, defaults to the newest API version available to your app.
v23.0
<BUSINESS_PHONE_NUMBER_ID>
String
Required.
WhatsApp business phone number ID.
106540352242922
<BUTTON_INDEX>
Integer
Required.
Indicates order in which button should appear, if the template uses multiple buttons.
Buttons are zero-indexed, so setting value to 0 will cause the button to appear first, and another button with an index of 1 will appear next, etc.
0
<COUPON_CODE>
String
Required.
The coupon code to be copied when the customer taps the button. Only accepting alphanumeric characters.
Maximum 20 characters.
25OFF
<TEMPLATE_NAME>
String
Required.
Name of the template to be sent.
coupon_code_fall2023_25off
<TEMPLATE_LANGUAGE>
String
Required.
The template’s language and locale code.
en_US
<USER_PHONE_NUMBER>
String
Required.
The WhatsApp ID or phone number of the customer to send the message to. See Phone Number Formats.
+16505551234

Response syntax

Upon success the API will respond with:
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<WHATSAPP_USER_PHONE_NUMBER>",
      "wa_id": "<WHATSAPP_USER_ID>"
    }
  ],
  "messages": [
    {
      "id": "<WHATSAPP_MESSAGE_ID>",
      "group_id": "<GROUP_ID>", <!-- Only included if messaging a group -->
      "message_status": "<PACING_STATUS>" <!-- Only included if sending a template -->
    }
  ]
}

Response parameters

Placeholder Description Sample Value
<GROUP_ID>
String
The string identifier of a group made using the Groups API.
This field shows when messages are sent, received, or read from a group.
Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD
<PACING_STATUS>
String
Indicates template pacing status. The message_status property is only included in responses when sending a template message that uses a template that is being paced.
wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI4MjZGRDA0OUE2OTQ3RkEyMzcA
<WHATSAPP_USER_PHONE_NUMBER>
String
WhatsApp user’s WhatsApp phone number. May not match wa_id value.
+16505551234
<WHATSAPP_USER_ID>
String
WhatsApp user’s WhatsApp ID. May not match input value.
16505551234
<WHATSAPP_MESSAGE_ID>
String
WhatsApp Message ID. This ID appears in associated messages webhooks, such as sent, read, and delivered webhooks.
wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI4MjZGRDA0OUE2OTQ3RkEyMzcA

Example Request

curl 'https://graph.facebook.com/v25.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "to": "16505551234",
  "type": "template",
  "template": {
    "name": "coupon_code_fall2023_25off",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "25OFF"
          },
          {
            "type": "text",
            "text": "25%"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "COPY_CODE",
        "index": 1,
        "parameters": [
          {
            "type": "coupon_code",
            "coupon_code": "25OFF"
          }
        ]
      }
    ]
  }
}'

Example Response

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "16505551234",
      "wa_id": "16505551234"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBIxRjk1REYzMDBERDE3RUI0RDYA"
    }
  ]
}
Did you find this page helpful?
Thumbs up icon
Thumbs down icon