Skip to main content

Coupon code templates | Developer Documentation

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"
    }
  ]
}
    
    
            
    
        
    
    
    
        
    
            
    
                
                
    
                    
                    
                
    
            
    
            
            
    
                                            
    
        
    
    
    

    

    
    
    

    
            
    
            
    

    
    
        
    
            
            
        
    
            
    

    
    
        
    
                    
    

        
    No comments to display
    

            
    

    

    

                
    
        
    
                
    
        
    
    
    

    
    

    
    
    
        
    
             Back to top