Create a countdown
One request with a deadline, a duration, or a repeating schedule. You get a timer ID back immediately.
Countdown Timer API
for Developers
Add live countdowns to any application with a simple Countdown Timer API. Create countdowns in seconds, retrieve the remaining time in real time, and receive webhooks the moment they expire.
Free Sandbox with any account · no monthly request cap
paused550e8400-e29b-41d4-a716-446655440000
A live demo countdown, currently 6 days, 4 hours and 12 minutes from finishing.
0%
GET /v1/timers/{timer_id}/status
{
"data": {
"status": "paused",
"target_at": "2026-08-11T04:12:00Z",
"remaining": { "total_seconds": 533520 },
"ended": false
}
}→ webhook rule armed for timer.completed
Live demo — the controls work
Definition
What is a countdown timer API?
A countdown timer API lets developers create, manage, and monitor countdown timers without building their own scheduling and timer infrastructure. Your application creates a timer using an end date or a duration, retrieves its current state whenever it needs to, and reacts to timer events through API responses or webhooks.
CountdownShare computes the remaining time on the server, so a browser with a wrong clock, a mobile app in the background, and an email opened three days later all report the same answer. When a countdown reaches a moment you care about, a signed webhook arrives at your endpoint instead of your application polling for it.
REST over HTTPS · JSON · bearer API keys · OpenAPI 3.1 · Sandbox and Production
The whole integrationFull create reference
Create a countdown with the REST API.
One authenticated request creates the timer. The response carries the timer ID, its revision, the remaining seconds, and — once published — the hosted page you can share.
Request
POST /v1/timers
Authorization: Bearer cs_live_...
Idempotency-Key: product-launch-2030
Content-Type: application/json
{
"name": "Product launch",
"type": "fixed",
"deadline_at": "2030-01-01T14:00:00Z",
"publish": true
}Response
201 Created
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "fixed",
"status": "published",
"revision": 1,
"deadline_at": "2030-01-01T14:00:00.000Z",
"remaining_seconds": 2692800,
"outputs": {
"public_page_url":
"https://countdownshare.com/api/c/550e8400-..."
}
},
"request_id": "7b82b7f7-4d13-497b-9f20-58d46fd7a510"
}What the API doesPOST GET PATCH ACTIONS WEBHOOK
Five calls cover the whole lifecycle.
Retrieve the remaining time
Status, target time, days, hours, minutes, seconds, progress, and whether it has ended.
Update a timer in flight
Move the deadline, change the duration, or swap the schedule. Send the current revision in If-Match.
Start, pause, resume, reset
Duration timers are controlled from your application, not from a dashboard.
Get called when it matters
A signed HTTPS POST to your endpoint when a rule you defined matches. No polling for zero.
How developers create a countdownPOST /v1/timers GET /v1/timers/{id}/status POST /v1/timers/{id}/webhook-rules
Three calls, and one of them calls you.
Create the countdown
Send a name, a type, and its timing. The response contains the timer ID you use from then on.
Read it on demand
Call it whenever you render. The server computes the remaining time, so no client clock can drift.
Be notified
Point a rule at a destination you registered. We call you when the condition matches.
← we call youSupported timer types
Four shapes of time.
Every type uses the same endpoints. The type you send at creation decides which timing field is required.
Fixed-date countdown
type: fixedCounts down to one exact ISO 8601 deadline.
Duration timer
type: durationRuns for a set number of seconds. Start, pause, resume, reset.
Recurring countdown
type: recurringRepeats daily, weekly, monthly, or on an RRULE, in any IANA timezone.
Personalized countdown
type: personalizedA separate deadline per external_user_id, from a single timer.
Supported timer actions
Everything after create.
Managing a timer never counts against your monthly allowance. Only creating and duplicating do.
- Start · pause · resume · reset
POST /timers/{id}/actions - Publish or unpublish
PATCH /timers/{id} - Duplicate
POST /timers/{id}/duplicate - Archive and restore
POST /timers/{id}/archive · /restore - Delete
DELETE /timers/{id} - Read change history
GET /timers/{id}/activity
Countdown webhooks
Stop polling for zero.
Register a webhook destination once, then attach rules to the timers you care about. Each rule is a condition; when it matches, we send a signed HTTPS POST to your endpoint and retry it if your service is down.
Webhook referencestatus equals endedThe countdown reaches zeroremaining_seconds ≤ 3600One hour leftprogress_percent ≥ 75Three quarters elapsedaction equals pausedSomeone paused the timerserver_time ≥ 2030-01-01T14:00:00ZA wall-clock moment passesrecurrence_cycle equals completedA repeating cycle finishes
Display and embed options
Render it yourself, or don't.
Hosted pages, embeds, and email images are returned for published production timers. The JSON status endpoint works for every timer, in both environments.
Output referenceYour own interface
Read the status endpoint and render the numbers however your product needs.
Hosted countdown page
A shareable page at /api/c/{timer_id}, or /api/t/{timer_id} for duration timers.
Website embed
A responsive iframe snippet returned ready to paste into any page.
Email countdown
An animated image that renders the current remaining time when the inbox opens it.
Developer use cases
What teams build with a countdown API.
Product launches
One countdown drives your marketing site, your embed, and your launch-day email.
Flash sales
A fixed deadline per campaign, with a webhook that closes the offer at zero.
Booking and reservation holds
A duration timer per cart or seat hold, released by webhook when it expires.
Trial expiry
A personalized countdown per customer, created once from a single timer definition.
Events and webinars
A recurring countdown that resets itself for the next session in the right timezone.
Auctions and bidding
Server-computed remaining time so no bidder sees a different clock.
Why an API
The timer is easy. The infrastructure is not.
Counting down is a subtraction. Everything around it — firing on time, agreeing across devices, surviving a failed webhook, and getting daylight saving right — is the part that takes a quarter to build.
Scheduling you do not run
No cron, no job queue, no worker to keep alive so a deadline fires on time.
One authoritative clock
Remaining time is computed server-side, so every device and every email agrees.
Delivery that retries
Failed webhooks retry on a backoff schedule and can be replayed from your dashboard.
Timezones and DST handled
Recurring schedules are evaluated against the IANA database, including the awkward days.
Supported integration environments
If it can send an HTTP request, it can run a countdown.
JavaScript and TypeScript
Plain fetch from Node.js, Deno, Bun, or an edge runtime. No SDK to install.
React and Next.js
Call the status endpoint from a route handler or server component and hydrate your own timer UI.
Any backend language
HTTP and JSON with bearer authentication. Generate a client from the OpenAPI 3.1 spec.
No-code and automation tools
Anything that can send an HTTP request and receive a webhook can drive a timer.
Keys are environment-bound: cs_test_ keys reach Sandbox only and cs_live_ keys reach Production only, so test data can never appear on a customer-facing page.
Pricing model
You pay for countdowns you create, not for reading them.
No plan has a monthly cap on API requests. A per-minute rate limit applies — 300 requests per minute in Production, 30 in Sandbox.
Sandbox
Free
100 test timers per month, with any CountdownShare account
No monthly request cap
Starter
$9/ month
1,000 new timers per month · 5 webhook destinations
No monthly request cap
Growth
Most used$49/ month
10,000 new timers per month · 25 webhook destinations
No monthly request cap
Questions
Countdown Timer API FAQ
What is a countdown timer API?
A countdown timer API lets developers create, manage, and monitor countdown timers over HTTP instead of building their own scheduling and timer infrastructure. Your application creates a timer with an end date or a duration, retrieves its current state whenever it needs to, and reacts to timer events through API responses or webhooks.
How do I create a countdown using the API?
Send a POST request to /v1/timers with a name, a type of fixed, duration, recurring, or personalized, and the matching timing field: deadline_at for a fixed date, or duration_seconds for a duration. Include an Idempotency-Key header so a retried request cannot create a second timer. The response returns the timer ID you use for every later call.
How do I retrieve the remaining time?
Call GET /v1/timers/{timer_id}/status. It returns the current status, the server time, the target time, the remaining time as total seconds plus days, hours, minutes, and seconds, a progress value, and whether the timer has ended. Because the remaining time is computed on the server, every client sees the same clock.
Can I update a countdown after creating it?
Yes. PATCH /v1/timers/{timer_id} changes the name, deadline, duration, timezone, recurrence schedule, expiry behavior, metadata, or publication state. Send the timer’s current revision in an If-Match header; if the timer changed since you read it the API returns a revision conflict instead of silently overwriting.
Can I pause and resume a timer?
Yes, for duration timers. POST /v1/timers/{timer_id}/actions with an action of start, pause, resume, or reset. Fixed-date countdowns count down to an exact instant, so they are changed by moving deadline_at rather than by pausing.
Does the API support webhooks?
Yes. Register a webhook destination once, then attach rules to individual timers. A rule is a condition on status, remaining_seconds, progress_percent, server_time, action, or recurrence_cycle. Matching rules produce a signed HTTPS POST to your endpoint, retried automatically on failure.
What happens when a countdown reaches zero?
The timer status becomes ended and remaining time reports zero. Any webhook rule watching for that moment fires. Hosted pages and embeds follow the expiry behavior you configured: show a message, hide the timer, or redirect.
Can I embed a countdown on my website?
Yes. A published production timer returns a hosted page URL, a responsive website embed snippet, and an email-safe image, alongside the JSON status endpoint you would use to build your own interface.
Can I use the API with JavaScript or Node.js?
Yes. The API is REST over HTTPS with JSON bodies and bearer authentication, so fetch from Node.js, Deno, Bun, React, or Next.js works without an SDK. An OpenAPI 3.1 specification is published if you would rather generate a typed client.
Does the API support recurring timers?
Yes. A recurring timer repeats on a daily, weekly, monthly, or custom RRULE schedule with a local time and an IANA timezone. Each completed cycle can trigger a webhook, and the timer advances to the next occurrence on its own.
How are API usage and pricing calculated?
Plans are priced on the number of new timers you create each month. Creating a timer counts once, and duplicating one counts as a new timer. Reading, updating, controlling, publishing, archiving, and deleting existing timers do not count again.
Are read requests limited?
There is no monthly cap on API requests on any plan, so you can read a timer as often as you need. A per-minute rate limit protects the service: 300 requests per minute in production and 30 per minute in Sandbox.
Is there a free plan?
Every CountdownShare account includes a free Sandbox environment with its own API key: 100 test timers per month, one webhook destination, and 100 webhook deliveries. Sandbox timers cannot be published, so a paid plan is required for public pages, embeds, and production traffic.
Your first countdown is one POST away.
Create an account, generate a Sandbox key, and the docs open with a request you can paste into a terminal.