DocumentazioneEngagement Platform API
Sign inGet started
Guides
API

Limited Time Offer Templates

Limited time offer templates display promotional messages with an expiration date and a countdown timer. They create urgency by showing users when an offer expires, and can include a coupon code and a link to take action.

Block Structure

A limited time offer template uses a single whatsapp-limited-time-offer block:
ComponentRequiredDescription
HeaderNoImage or file (video) header
Body textYesMain message text (max 1024 characters)
Limited time offerYesOffer text and expiration date for the countdown
Link actionYesButton linking to the offer page
Coupon actionConditionalCopy-code button for a discount code. Required when the limited time offer sets expiresAt, optional otherwise -- see Coupon Action
Here's how a limited time offer template renders on WhatsApp, showing the offer badge with countdown, image header, body, and action buttons:
The offer badge (with the tag icon) displays the offer text, expiration, and coupon code. WhatsApp adjusts the countdown display based on how far away the expiration is -- see countdown display states below.

Header

Limited time offer templates support image or file (video) headers. Text headers are not supported.
Image header:
Esempio di codice
{
  "type": "image",
  "image": {
    "mediaUrl": "https://example.com/images/limited-offer.jpg"
  }
}
Video header:
Esempio di codice
{
  "type": "file",
  "file": {
    "mediaUrl": "https://example.com/videos/offer-promo.mp4",
    "contentType": "video/mp4"
  }
}
If you need to host media, use the Media Library API to upload files and get a mediaUrl. See Image Template Blocks -- Uploading media for the full upload flow.

Body

The body is mandatory and should describe the offer with compelling copy.
Esempio di codice
{
  "type": "text",
  "text": {
    "text": "Exclusive deal just for you! Get 40% off on all premium items. Don't miss out -- this offer expires soon!"
  }
}

Limited Time Offer Component

The limited time offer component defines the offer text and expiration. WhatsApp displays a countdown timer based on the expiresAt value.
Esempio di codice
{
  "type": "limited-time-offer",
  "limitedTimeOffer": {
    "text": "40% OFF Today!",
    "expiresAt": "2024-12-31T23:59:59Z"
  }
}
PropertyRequiredDescription
textYesThe offer headline displayed to the user (max 16 characters)
expiresAtNoISO 8601 timestamp for when the offer expires. When provided, WhatsApp shows a countdown timer, and a couponAction becomes required -- activating without one fails with couponAction is required. Omit expiresAt entirely to build an offer with no countdown; an empty string still counts as provided. Can be a variable for dynamic expiration.

Dynamic expiration

Use a variable to set the expiration at send time:
Esempio di codice
{
  "type": "limited-time-offer",
  "limitedTimeOffer": {
    "text": "Flash Sale!",
    "expiresAt": "{{offerExpiry}}"
  }
}

Countdown display states

WhatsApp adjusts the offer badge based on how much time remains:
Future date -- shows the expiration date (e.g., "Offer ends on 31 Dec"):
Expires today -- switches to showing the exact time (e.g., "Ends today at 12:35"):
Expired -- the offer badge shows "Offer ended", the coupon code is removed, and the copy-code button disappears. The link button remains:

Link Action

A link button is required. It provides the user with a direct path to take action on the offer.
Esempio di codice
{
  "type": "link-action",
  "linkAction": {
    "text": "Shop now",
    "url": "https://example.com/limited-offer"
  }
}

Coupon Action

Include a copy-code button for a promotional code. This is required when the limited time offer component sets expiresAt, and optional when it does not -- a coupon code on its own never requires an expiry.
An offer code with no expiry is valid and renders without a countdown. If the code has no time limit at all, consider a Coupon Template instead.
Esempio di codice
{
  "type": "copy-code-action",
  "copyCodeAction": {
    "code": "{{promoCode}}"
  }
}

Complete Example

Esempio di codice
{
  "defaultLocale": "en",
  "deployments": [
    {
      "key": "whatsappTemplateName",
      "platform": "whatsapp",
      "value": "limited_time_sale"
    },
    {
      "key": "whatsappCategory",
      "platform": "whatsapp",
      "value": "MARKETING"
    },
    {
      "key": "whatsappAllowCategoryChange",
      "platform": "whatsapp",
      "value": "true"
    }
  ],
  "variables": [
    {
      "key": "promoCode",
      "description": "Promotional discount code",
      "type": "string",
      "format": "none",
      "examplesLocale": {
        "en": {
          "exampleValueStrings": ["HURRY40"]
        }
      }
    },
    {
      "key": "customerName",
      "description": "Customer's first name",
      "type": "string",
      "format": "none",
      "examplesLocale": {
        "en": {
          "exampleValueStrings": ["Maria"]
        }
      }
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "whatsapp",
      "channelGroupIds": [
        "3f979241-dea3-4f55-b7bb-d769eec27e51"
      ],
      "blocks": [
        {
          "type": "whatsapp-limited-time-offer",
          "whatsappLimitedTimeOffer": {
            "header": {
              "type": "image",
              "image": {
                "mediaUrl": "https://example.com/images/flash-sale-banner.jpg"
              }
            },
            "body": {
              "type": "text",
              "text": {
                "text": "Hi {{customerName}}, our biggest sale of the year is here! Get 40% off everything with code {{promoCode}}. Hurry, the clock is ticking!"
              }
            },
            "limitedTimeOffer": {
              "type": "limited-time-offer",
              "limitedTimeOffer": {
                "text": "40% OFF Today!",
                "expiresAt": "2024-12-31T23:59:59Z"
              }
            },
            "couponAction": {
              "type": "copy-code-action",
              "copyCodeAction": {
                "code": "{{promoCode}}"
              }
            },
            "linkAction": {
              "type": "link-action",
              "linkAction": {
                "text": "Shop the sale",
                "url": "https://example.com/flash-sale"
              }
            }
          }
        }
      ]
    }
  ],
  "supportedPlatforms": ["whatsapp"]
}

Without Coupon Code

If you don't need a coupon code, omit the couponAction and expiresAt:
Esempio di codice
{
  "type": "whatsapp-limited-time-offer",
  "whatsappLimitedTimeOffer": {
    "body": {
      "type": "text",
      "text": {
        "text": "Free shipping on all orders -- today only! No code needed."
      }
    },
    "limitedTimeOffer": {
      "type": "limited-time-offer",
      "limitedTimeOffer": {
        "text": "Free Shipping"
      }
    },
    "linkAction": {
      "type": "link-action",
      "linkAction": {
        "text": "Shop now",
        "url": "https://example.com/free-shipping"
      }
    }
  }
}

Related