# Limited-Time Offer Templates

{% hint style="info" %}
Limited-Time Offer Templates are only available while using Cloud API. 
{% endhint %}

Limited-time offer templates allow you to display expiration dates and running countdown timers for offer codes in template messages, making it easy for you to communicate time-bound offers and drive customer engagement.

<figure><img src="/files/y4HHMnLJIvJaMtmkI8IQ" alt="" width="363"><figcaption></figcaption></figure>

## Limitations <a href="#limitations" id="limitations"></a>

* Only templates categorized as `MARKETING` are supported.
* Footer components are not supported.
* Users who view a limited-time offer template message using that WhatsApp web app or desktop app will not see the offer, but will instead see a message indicating that they have received a message but that it's not supported in the client they are using.

## Template Creation <a href="#creating-coupon-code-templates" id="creating-coupon-code-templates"></a>

Use the create template [endpoint](https://docs.360dialog.com/docs/messaging-api/api-reference/templates#post-v1-configs-templates) to create coupon code templates.

#### Headers

| Name         | Type   | Description |
| ------------ | ------ | ----------- |
| D360-API-KEY | string |             |

{% tabs %}
{% tab title="200 " %}

```json
{
  "id": "546151681022936",
  "status": "PENDING",
  "category": "MARKETING"
}
```

{% endtab %}
{% endtabs %}

Once your template is approved, you can use Cloud API to send it in a template message.

#### Post Body <a href="#post-body" id="post-body"></a>

```json
{
  "name": "<TEMPLATE_NAME>",
  "language": "<TEMPLATE_LANGUAGE>",
  "category": "marketing",
  "components": [

    /* Header component optional */
    {
      "type": "header",
      "format": "<HEADER_FORMAT>",
      "example": {
        "header_handle": [
          "<HEADER_ASSET_HANDLE>"
        ]
      }
    },

    /* Limited-time offer component required */
    {
      "type": "limited_time_offer",
      "limited_time_offer": {
        "text": "<LIMITED_TIME_OFFER_TEXT>",
        "has_expiration": <HAS_EXPIRATION>
      }
    },

    /* Body component required */
    {
      "type": "body",
      "text": "<BODY_TEXT>",
      "example": {
        "body_text": [<BODY_TEXT_VARIABLE_EXAMPLES>]
      }
    },

    /* Copy code button component required if "has_expiration" is set to true.
       If set to false but want to use a copy code button, it must appear
       first in the "buttons" array. URL button component is always required. */
    {
      "type": "buttons",
      "buttons": [
        {
          "type": "copy_code",
          "example": "<OFFER_CODE_EXAMPLE>"
        },
        {
          "type": "url",
          "text": "<URL_BUTTON_TEXT>",
          "url": "<URL_BUTTON_URL>",
          "example": [
            "<URL_EXAMPLE_WITH_VARIABLE_EXAMPLE>"
          ]
        }
      ]
    }
  ]
}

```

#### Properties <a href="#body-properties" id="body-properties"></a>

| Placeholder                                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Example Value                                                                         |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| <p><code>\<BODY\_TEXT></code></p><p><em>String</em></p>                               | <p><strong>Required.</strong></p><p></p><p>Body component text. Supports variables.<br></p><p>Maximum 600 characters.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `Good news, {{1}}! Use code {{2}} to get 25% off all Caribbean Destination packages!` |
| <p><code>\<BODY\_TEXT\_VARIABLE\_EXAMPLES></code></p><p><em>Array of strings</em></p> | <p><strong>Required if body component text uses variables.</strong><br></p><p>Array of example variable strings.</p><p></p><p>Must supply examples for all placeholders in <code>\<BODY\_TEXT></code> string.<br></p><p>No maximum, but counts against <code>\<BODY\_TEXT></code> maximum.</p>                                                                                                                                                                                                                                                                                                        | `["Pablo","CARIBE25"]`                                                                |
| <p><code>\<HAS\_EXPIRATION></code></p><p><em>Boolean</em></p>                         | <p><strong>Optional.</strong><br></p><p>Set to <code>true</code> to have the <a href="#offer-expiration-details">offer expiration details</a> appear in the delivered message.<br></p><p>If set to <code>true</code>, the copy code button component must be included in the <code>buttons</code> array, and must appear first in the array.<br></p><p>If set to <code>false</code>, offer expiration details will not appear in the delivered message and the copy code button component is optional. If including the copy code button, it must appear first in the <code>buttons</code> array.</p> | `true`                                                                                |
| <p><code>\<HEADER\_ASSET\_HANDLE></code></p><p><em>Media asset handle</em></p>        | <p><strong>Required if using an image or video header.</strong><br></p><p>Uploaded media asset handle. Use the <a href="/pages/-MFBnCAv4krLCm053Dqr#resumable-upload-api-for-profile-pictures">Resumable Upload API</a> to generate an asset handle.</p>                                                                                                                                                                                                                                                                                                                                              | `4::aW...`                                                                            |
| <p><code>\<HEADER\_FORMAT></code></p><p><em>Enum</em></p>                             | <p><strong>Required if using a header.</strong></p><p></p><p>Can be <code>IMAGE</code>, or <code>VIDEO</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `IMAGE`                                                                               |
| <p><code>\<LIMITED\_TIME\_OFFER\_TEXT></code></p><p><em>String</em></p>               | <p><strong>Required.</strong></p><p></p><p>Offer details text.</p><p></p><p>Maximum 16 characters.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `Expiring offer!`                                                                     |
| <p><code>\<OFFER\_CODE\_EXAMPLE></code></p><p><em>String</em></p>                     | <p><strong>Required.</strong><br></p><p>Example offer code.</p><p></p><p>Maximum 15 characters.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `CARIBE25`                                                                            |
| <p><code>\<TEMPLATE\_LANGUAGE></code></p><p><em>Enum</em></p>                         | <p><strong>Required.</strong><br></p><p>Template <a href="https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/supported-languages">language and locale code</a>.</p>                                                                                                                                                                                                                                                                                                                                                                                              | `en_US`                                                                               |
| <p><code>\<TEMPLATE\_NAME></code></p><p><em>String</em></p>                           | <p><strong>Required.</strong><br></p><p>Template name.</p><p></p><p>Maximum 512 characters.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `limited_time_offer_caribbean_pkg_2023`                                               |
| <p><code>\<URL\_BUTTON\_TEXT></code></p><p><em>String</em></p>                        | <p><strong>Required.</strong></p><p></p><p><a href="/pages/iCJsxJC1tQG0F9veyQDs#url-buttons">URL button </a>label text. Supports 1 variable.</p><p></p><p>25 characters maximum.</p>                                                                                                                                                                                                                                                                                                                                                                                                                  | `Book now!`                                                                           |
| <p><code>\<URL\_BUTTON\_URL></code></p><p><em>String</em></p>                         | <p><strong>Required.</strong><br></p><p>URL of website that loads in the device's default mobile web browser when the <a href="/pages/iCJsxJC1tQG0F9veyQDs#url-buttons">URL button </a>is tapped by the WhatsApp user.</p><p></p><p>Supports 1 variable appended to the end of the URL string.<br></p><p>Maximum 2000 characters.</p>                                                                                                                                                                                                                                                                 | `https://awesomedestinations.com/offers?code={{1}}`                                   |
| <p><code>\<URL\_EXAMPLE\_WITH\_VARIABLE\_EXAMPLE></code></p><p><em>String</em></p>    | <p><strong>Required if URL uses a variable.</strong></p><p></p><p>Example URL with example variable appended to the end.<br></p><p>No maximum, but value counts against <code>\<URL\_BUTTON\_URL></code> maximum.</p>                                                                                                                                                                                                                                                                                                                                                                                 | `https://awesomedestinations.com/offers?ref=n3mtql`                                   |

#### Offer Expiration Details <a href="#offer-expiration-details" id="offer-expiration-details"></a>

The delivered message can display an offer expiration details section with a heading, an optional expiration timer, and the offer code itself.

<figure><img src="/files/4945xPEbFCttTkyzOwkB" alt="" width="375"><figcaption></figcaption></figure>

The expiration timer is a text string that is not customizable, but it will change to red text if the message is viewed and the offer code is expiring within the next hour. (You include the actual offer code and its expiration timestamp when you send the template in a template message.)

**Example Request**

This is an example request to create a limited-time offer template that uses:

* an image header component
* body text component with variables
* the limited time offer component
* a copy code button
* a button URL with a variable

```json
{
  "name": "limited_time_offer_caribbean_pkg_2023",
  "language": "en_US",
  "category": "marketing",
  "components": [
    {
      "type": "header",
      "format": "image",
      "example": {
        "header_handle": [
          "4::aW..."
        ]
      }
    },
    {
      "type": "limited_time_offer",
      "limited_time_offer": {
        "text": "Expiring offer!",
        "has_expiration": true
      }
    },
    {
      "type": "body",
      "text": "Good news, {{1}}! Use code {{2}} to get 25% off all Caribbean Destination packages!",
      "example": {
        "body_text": [
          [
            "Pablo",
            "CARIBE25"
          ]
        ]
      }
    },
    {
      "type": "buttons",
      "buttons": [
        {
          "type": "copy_code",
          "example": "CARIBE25"
        },
        {
          "type": "url",
          "text": "Book now!",
          "url": "https://awesomedestinations.com/offers?code={{1}}",
          "example": [
            "https://awesomedestinations.com/offers?ref=n3mtql"
          ]
        }
      ]
    }
  ]
}
```

## Sending Coupon Templates <a href="#sending-coupon-templates" id="sending-coupon-templates"></a>

Use this [endpoint ](https://docs.360dialog.com/docs/messaging-api/api-reference/messages#post-messages)to send approved coupon code templates in template messages.&#x20;

**Post Body**

```json
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<CUSTOMER_PHONE_NUMBER>",
  "type": "template",
  "template": {
    "name": "<TEMPLATE_NAME>",
    "language": {
      "code": "<TEMPLATE_LANGUAGE_CODE>"
    },
    "components": [

      /* Required if template uses header, otherwise omit */
      {
        "type": "header",
        "parameters": [
          {
            "type": "<HEADER_TYPE>",
            "<HEADER_TYPE>": {
              "id": "<HEADER_ASSET_ID>"
            }
          }
        ]
      },

      /* Body and params required if templates uses body params, otherwise omit */
      {
        "type": "body",
        "parameters": [
          <BODY_VARIABLES>
        ]
      },

      /* Required if template uses offer expiration details, otherwise omit */
      {
        "type": "limited_time_offer",
        "parameters": [
          {
            "type": "limited_time_offer",
            "limited_time_offer": {
              "expiration_time_ms": <EXPIRATION_TIME>
            }
          }
        ]
      },

      /* Copy code button required if template uses offer expiration details, or 
         if uses a copy code button without the offer expiration details */
      {
        "type": "button",
        "sub_type": "copy_code",
        "index": 0,
        "parameters": [
          {
            "type": "coupon_code",
            "coupon_code": "<OFFER_CODE>"
          }
        ]
      },

      /* Required */
      {
        "type": "button",
        "sub_type": "url",
        "index": <URL_BUTTON_INDEX>,
        "parameters": [
          {
            "type": "text",
            "text": "<URL_VARIABLE>"
          }
        ]
      }
    ]
  }
}
```

#### Properties <a href="#body-properties" id="body-properties"></a>

| Placeholder                                                            | Description                                                                                                                                                                                                                          | Example Value                                                      |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| <p><code>\<BODY\_VARIABLES></code></p><p><em>Array of objects</em></p> | <p><strong>Required if template body text uses variables.</strong></p><p></p><p>Body text variable values. Define each variable as an individual object.</p>                                                                         | `{"type":"text","text":"Pablo"},{"type":"text","text":"CARIBE25"}` |
| <p><code>\<CUSTOMER\_PHONE\_NUMBER></code></p><p><em>String</em></p>   | <p><strong>Required.</strong><br></p><p>Phone number of customer who the template message should be sent to.</p>                                                                                                                     | `+16505555555`                                                     |
| <p><code>\<EXPIRATION\_TIME></code></p><p><em>Unix timestamp</em></p>  | <p><strong>Required.</strong></p><p></p><p>Offer code expiration time as a UNIX timestamp in milliseconds.</p>                                                                                                                       | `1698562800000`                                                    |
| <p><code>\<HEADER\_ASSET\_ID></code></p><p><em>Media asset ID</em></p> | <p><strong>Required.</strong></p><p></p><p>Uploaded media asset ID. Use the<a href="/pages/-MfgDkcifr0eL9Ye0C46#upload-media"> /media </a>endpoint to generate an ID.</p>                                                            | `1602186516975000`                                                 |
| <p><code>\<HEADER\_TYPE></code></p><p><em>String</em></p>              | <p><strong>Required.</strong><br></p><p>Header type used by the template. Values can be <code>image</code> or <code>video</code>.</p>                                                                                                | `image`                                                            |
| <p><code>\<OFFER\_CODE></code></p><p><em>String</em></p>               | <p><strong>Required if template uses offer expiration details or a copy code button.</strong></p><p></p><p>Offer code.</p><p></p><p>Maximum 15 characters.</p>                                                                       | `CARIBE25`                                                         |
| <p><code>\<TEMPLATE\_LANGUAGE\_CODE></code></p><p><em>Enum</em></p>    | <p><strong>Required.</strong><br></p><p>The template's <a href="https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/supported-languages">language and locale code</a>.</p>                       | `en_US`                                                            |
| <p><code>\<TEMPLATE\_NAME></code></p><p><em>String</em></p>            | <p><strong>Required.</strong></p><p></p><p>The template's name.</p>                                                                                                                                                                  | `limited_time_offer_caribbean_pkg_2023`                            |
| <p><code>\<URL\_BUTTON\_INDEX></code></p><p><em>Integer</em></p>       | <p><strong>Required.</strong></p><p></p><p>URL button index. If the template uses a copy code button, value must be <code>1</code>.<br></p><p>If the template does not use a copy code button, the value must be <code>0</code>.</p> | `1`                                                                |
| <p><code>\<URL\_VARIABLE></code></p><p><em>String</em></p>             | <p><strong>Required if URL uses a variable.</strong><br></p><p>URL variable value.</p><p></p><p>No maximum but value counts against URL string maximum of 2000 characters.</p>                                                       | `n3mtql`                                                           |

**Example Request**

Example request to send a limited-time offer template that uses:

* an image header
* body text variables
* the offer expiration details
* a copy code button
* a URL button with a variable

```json
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "16505555555",
  "type": "template",
  "template": {
    "name": "limited_time_offer_caribbean_pkg_2023",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "id": "1602186516975000"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Pablo"
          },
          {
            "type": "text",
            "text": "CARIBE25"
          }
        ]
      },
      {
        "type": "limited_time_offer",
        "parameters": [
          {
            "type": "limited_time_offer",
            "limited_time_offer": {
              "expiration_time_ms": 1209600000
            }
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "copy_code",
        "index": 0,
        "parameters": [
          {
            "type": "coupon_code",
            "coupon_code": "CARIBE25"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 1,
        "parameters": [
          {
            "type": "text",
            "text": "n3mtql"
          }
        ]
      }
    ]
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.360dialog.com/partner/messaging/template-messages/limited-time-offer-templates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.