Create Countdown Timer

POST 
/countdown-timer/timers

Create a countdown timer for the access token's location

Request

Version stringrequired

API Version

Available optionsv3

application/json

application/json

Body

Bodyrequired

namestringrequired

Timer name

timerTypestringrequired
Timer type
Available optionsfixeddynamicrecurring
templateIdstringrequired

Template ID from the list-templates endpoint

endDatestring

End date in ISO 8601 format. Required for fixed timers.

timezonestring

Valid IANA timezone identifier

timerDurationobject

Timer duration. Required for dynamic and recurring timers.

waitTimeobject

Wait time between recurring loops

designMetaobjectrequired

Design metadata for timer appearance. Get defaults from the templates endpoint and customize as needed.

hideTimerForAppleMailboolean
Hide timer for Apple Mail clients
Default value: false
dynamicTimerParamsobject

Dynamic timer parameters. Required for dynamic timers.

linksobject

Timer redirect links for active, expired, and non-user states

expiryImageLinkstring

Image to show when timer expires

bgImageLinkstring

Background image for timer

Example (auto)

{
  "name": "Flash Sale Timer",
  "timerType": "fixed",
  "templateId": "minimal",
  "endDate": "2026-04-01T00:00:00.000Z",
  "timezone": "America/New_York",
  "timerDuration": {
    "days": 1,
    "hours": 2,
    "minutes": 0,
    "seconds": 0
  },
  "waitTime": {
    "days": 0,
    "hours": 0,
    "minutes": 30,
    "seconds": 0
  },
  "designMeta": {
    "backgroundColor": "#ffffff",
    "textColor": "#111827",
    "separatorColor": "#e5e7eb",
    "labels": {
      "days": "Days",
      "hours": "Hours",
      "minutes": "Minutes",
      "seconds": "Seconds"
    }
  },
  "hideTimerForAppleMail": false,
  "dynamicTimerParams": {
    "endTime": "17:00",
    "trigger": "sent"
  },
  "links": {
    "activeLink": "https://example.com/sale",
    "expiryLink": "https://example.com/expired",
    "notUserLink": "https://example.com/signup"
  },
  "expiryImageLink": "https://example.com/expiry.png",
  "bgImageLink": "https://example.com/bg.png"
}

application/json

Timer created successfully

application/json

Schema

Schema

idstringrequired

Timer ID

namestringrequired

Timer name

templateIdstring

Template ID

locationIdstringrequired

Location ID

statusstringrequired
Timer status
Available optionsactivedraftarchived
timerTypestringrequired
Timer type
Available optionsfixeddynamicrecurring
endDatestring

End date (ISO 8601)

startDatestring

Start date (ISO 8601)

timezonestring

Timezone

designMetaobject

Design metadata for timer appearance

timerDurationobject

Timer duration

linksobject

Timer links

trackingLinkstring

Tracking link URL

hasLinkboolean

Whether timer has an active link

previewUrlstring

Preview image URL

thumbnailUrlstring

Thumbnail image URL

expiryImageLinkstring

Expiry image link

loopCountnumber

Number of recurring loops

waitTimeobject

Wait time between loops

hideTimerForAppleMailboolean

Hide timer for Apple Mail clients

hideRecurringTimerFunnelsboolean

Hide recurring timer in funnels

dynamicTimerParamsobject

Dynamic timer parameters

createdAtstring

Created timestamp

updatedAtstring

Updated timestamp

Example (auto)

{
  "id": "60d5f484f0f3c2001f2d5e4a",
  "name": "Flash Sale Timer",
  "templateId": "minimal",
  "locationId": "X9COWUStXtcLXTgBdqhm",
  "status": "draft",
  "timerType": "fixed",
  "endDate": "2026-04-01T00:00:00.000Z",
  "startDate": "2026-03-20T00:00:00.000Z",
  "timezone": "America/New_York",
  "designMeta": {
    "digitColor": "#a21043",
    "labelColor": "#a21043",
    "backgroundColor": "#ffffff",
    "counterFontSize": 50
  },
  "timerDuration": {
    "days": 1,
    "hours": 2,
    "minutes": 0,
    "seconds": 0
  },
  "links": {
    "activeLink": "https://example.com",
    "expiryLink": "https://example.com/expired"
  },
  "trackingLink": "https://t.example.com/abc123",
  "hasLink": true,
  "previewUrl": "https://storage.googleapis.com/cdn/countdown-timer/preview/abc123.gif",
  "thumbnailUrl": "https://storage.googleapis.com/cdn/countdown-timer/thumbnail/abc123.png",
  "expiryImageLink": "https://example.com/expiry.png",
  "loopCount": 3,
  "waitTime": {
    "minutes": 30
  },
  "hideTimerForAppleMail": false,
  "hideRecurringTimerFunnels": false,
  "dynamicTimerParams": {
    "endTime": "17:00",
    "trigger": "sent"
  },
  "createdAt": "2026-03-20T12:00:00.000Z",
  "updatedAt": "2026-03-20T12:00:00.000Z"
}