Wedding countdown
From 20 March 2026 to a wedding on 15 June 2027 there are 1 year, 2 months and 26 days left. Enter the ceremony date and the day you treat as today, and the countdown reads the way couples talk. Free in your browser.
- Free
- Runs in your browser
- No sign-up
- Your data stays on your device
Run — free
Worked example
- Wedding date
- 2027-06-15
- Reference date
- 2026-03-20
- Years
- 1
- Months
- 2
- Days
- 26
- Total days
- 452
How many years, months, and days remain until the wedding? A wedding countdown answers that planning question from two civil calendar dates you already know: the ceremony date printed on the invitation and a reference date you treat as today. This calculator never reads a host clock. You supply both values as YYYY-MM-DD days, the engine validates the wedding date as a real Gregorian day including leap February 29, and it decomposes the remaining span into whole years, leftover months, and leftover days.
What remaining time until a wedding means and how years, months and days appear
Remaining time until a wedding is a directed civil duration from an explicit reference day to one ceremony date, not a clock interval in hours and minutes and not an unordered span between two interchangeable dates. You start with the wedding date on the invitation — the fifteenth of June two thousand twenty-seven, the twenty-ninth of February in a leap year, a Saturday next spring — and the planning day you treat as today.
This calculator converts each civil triple into a serial day count, subtracts, and then decomposes the remaining span into whole years, leftover months, and leftover days using proleptic Gregorian rules. Whole months are walked with an end-of-month clamp so the thirty-first of January plus one month lands on the last day of February instead of inventing the thirty-first of February. Leftover days are then the ordinal remainder after those whole months.
The twentieth of March two thousand twenty-six to the fifteenth of June two thousand twenty-seven is one year, two months, and twenty-six days. A pair that falls on the same civil day is zero years, zero months, and zero days, labelled today. A wedding already behind the reference date is also zero remaining time, labelled past: the countdown answers how long is left, not how long ago the ceremony happened.
That is not the same as a generic calendar countdown that prints only a day integer, and it is not a retirement-style remainder built from two ages and a mean year of 365.2425 days. People who search for wedding countdown, days until our wedding, or wedding countdown calculator want this ceremony-to-today remainder printed as years, months, and days.
Where a wedding countdown earns its keep
Couples use a wedding countdown calculator so they can see years, months, and days left on a shared planning date without opening a spreadsheet or arguing about time zones. Wedding planners, coordinators, and venue desks drop the same two civil dates into a worksheet while they talk through vendor holds, tasting appointments, and rehearsal dinners, and they need a deterministic remainder that does not drift when someone reloads the page on another continent.
Invitation and stationery shops print remaining time on save-the-date cards and week-of itineraries, and they cannot call the system clock or invent a ceremony day the couple never supplied. Reminder and loyalty pipelines store the countdown against an audit reference date so a thirty-day, seven-day, or morning-of message fires without embedding a timezone database in every client. Failed validation does not consume balance.
Keep expectations honest: this capability measures remaining Gregorian civil years, months, and days from an explicit reference date to one wedding date; it does not skip weekends as business days, load religious calendars, convert lunar festival dates, default today from a server clock, or roll last year's anniversary forward. Pair it with a days-until-event tool when the search is only an integer day count, with a date-to-date helper when the pair is an unordered span, and with a clock countdown when hours and minutes matter.
Keep the dates inside the published year range, treat years months and days as the contract, and you get reproducible remaining time for planning notebooks, print shops, and public calculators without standing up a date library of your own.
What you can do with it
Couple planning and save-the-date timelines
Enter the ceremony date and today's planning date to see years, months, and days left before you lock vendors, fittings, and guest lists.
Planner and venue worksheets
Show a couple the remaining civil span to their wedding from two dates, with no host clock and no invented time zone.
Invitation shops and reminder pipelines
Print or schedule a wedding countdown against a pinned audit date so reprints and morning-of messages stay identical every time.
FAQ
What if the wedding date is already in the past?
The tool reports time left, not time elapsed since the ceremony.
How many days in total are left until my wedding?
Besides years, months and days, the result shows the total number of days. From 20 March 2026 to 15 June 2027 that is 452 days, the same span as 1 year, 2 months and 26 days.
Why do I have to type today's date myself?
Because the countdown never reads the clock on your device. You choose the reference day, so you can plan from any date, and the same two dates always give the same answer.
How are months counted when the wedding falls at the end of a month?
Whole months are counted first, and when a month is shorter the date moves to its last day: the thirty-first of January plus one month lands on the last day of February, not on a day that does not exist. The leftover days come after that.
Can I count down to a wedding on 29 February?
Yes, as long as the year is a leap year. A 29 February in any other year is not a real day, so it is rejected instead of being quietly moved to another date.
Related tools
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/life/wedding-countdown \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"wedding_date":"2027-06-15","reference_date":"2026-03-20"}'const res = await fetch("https://api.kit.forhosting.com/life/wedding-countdown", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"wedding_date": "2027-06-15",
"reference_date": "2026-03-20"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/life/wedding-countdown",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"wedding_date": "2027-06-15",
"reference_date": "2026-03-20"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/life/wedding-countdown", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"wedding_date":"2027-06-15","reference_date":"2026-03-20"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"wedding_date":"2027-06-15","reference_date":"2026-03-20"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/life/wedding-countdown", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"wedding_date": "2027-06-15",
"reference_date": "2026-03-20"
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "life.wedding_countdown",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Limits
year_min | 1 |
year_max | 9999 |
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |
Technical notes
It is not a generic days-until-any-event counter, not a clock remainder in hours and minutes, and not an anniversary roller that invents next year's date: you have a single ceremony day, and you want the remaining time printed the way couples and planners talk. When the wedding date is empty or is not a real calendar day the task fails with invalid_input and is not billed. Successful API calls use the published $0.002 base price.
Input contract, wedding-date validation, and the response shape
Each value must be a civil calendar day in YYYY-MM-DD form, for example two thousand twenty-seven hyphen zero six hyphen one five for the wedding and two thousand twenty-six hyphen zero three hyphen two zero for the planning day. Years range from one through nine thousand nine hundred ninety-nine, months must be one through twelve, and the day must exist in that month under Gregorian leap rules, including February twenty-nine only in a leap year. POST a JSON body with two required string fields: wedding_date, the ceremony day, and reference_date, the as-of day. Optional aliases wedding, ceremony, event_date, and date map to the wedding field; today, as_of, reference, from, and on map to the reference field so form builders and SDKs can keep familiar names. Impossible pairs such as two thousand twenty-three hyphen zero two hyphen twenty-nine are rejected with invalid_input instead of being shifted into March. An empty string, a missing wedding_date, a non-string value, or a wrong shape such as two thousand twenty-seven slash six slash fifteen fails with a message that names the field. Missing reference_date is also invalid_input, because the engine never invents today from the host clock. On success the body echoes the normalized wedding_date and reference_date as YYYY-MM-DD, then years, months, and days as non-negative integers for time still left, total_days as the signed civil-day distance (positive when the ceremony is ahead, zero when it is today, negative when it is already past), a formatted string such as one year, two months, 26 days, status as upcoming, today, or past, is_today as a boolean, and method set to gregorian_civil_ymd. Pair the integers with your own display if you prefer to hide zero years; this endpoint always returns all three so clients never have to re-run the decomposition. Failed validation does not consume prepaid balance.
Technical questions
How do I calculate years, months, and days until a wedding?
Send wedding_date and reference_date as YYYY-MM-DD. The API returns whole years, leftover months, leftover days, and a signed total_days count.
What happens if the wedding date is invalid?
The task fails with invalid_input. An empty wedding_date, a missing field, February 29 in a common year, and impossible day numbers are rejected and are not billed.
Does this wedding countdown use the server clock for today?
No. reference_date is required. The engine never reads the system clock, so results stay identical in browsers, scripts, and API workers.
What does the wedding countdown calculator cost?
The browser tool is free. API requests use prepaid KIT balance at $0.002 per successful call; invalid input is not billed.