curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

Add or subtract time from a date API

Add or subtract years, months, weeks, days, business days or hours to a date or date-time, with month-end and daylight-saving rules spelled out.

POST https://api.curatedapi.com/v1/calc/date/add

Calendar amounts (years, months, weeks, days) move the date on the calendar, keeping the clock time; hours, minutes and seconds are then added as elapsed time. So adding 1 day across a daylight saving change keeps 09:00 at 09:00, while adding 24 hours may not. Month additions that land on a day that does not exist use the month's last day, and the response says so.

Formula

months first (clamped to month end), then weeks and days, then elapsed time
  • Dates use the Gregorian calendar (ISO 8601). Adding months clamps to the month's last day (Jan 31 + 1 month = Feb 28 or 29).
  • Time zones come from the IANA time zone database in the pinned tzdata package; the version used is returned with each date-time result.
  • Business days skip the weekend days and holidays; the start day is not counted.

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
start required string Start date (YYYY-MM-DD) or date-time. At most 40 characters.
operation add | subtract
default add
Add or subtract. Options: add: add; subtract: subtract
years integer
default 0
Years to add. Allowed: >= 0 and <= 9999.
months integer
default 0
Months to add. Allowed: >= 0 and <= 120000.
weeks integer
default 0
Weeks to add. Allowed: >= 0 and <= 600000.
days integer
default 0
Days to add. Allowed: >= 0 and <= 4000000.
business_days integer Business days to add (alone, with a plain date). Allowed: >= 0 and <= 25000.
hours integer
default 0
Hours of elapsed time to add (date-times). Allowed: >= 0 and <= 100000000.
minutes integer
default 0
Minutes of elapsed time to add (date-times). Allowed: >= 0 and <= 100000000.
seconds decimal (string)
default 0
Seconds of elapsed time to add (date-times). Allowed: >= 0 and <= 10000000000.
timezone string IANA time zone for a date-time start without an offset.
weekend sat_sun | fri_sat | sun | fri | none
default sat_sun
Days that are not business days. Options: sat_sun: Saturday and Sunday; fri_sat: Friday and Saturday; sun: Sunday only; fri: Friday only; none: no weekend days
holidays list of date (YYYY-MM-DD) Dates that are not business days. Up to 1000 items.

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
resultstringThe resulting date or date-time.
weekdaystringDay of the week of the result.
result_utcstringThe result in UTC (date-times).
tz_databasestringTime zone database version used.

Examples

Month-end clamping

Requestcurl
curl https://api.curatedapi.com/v1/calc/date/add \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2026-01-31",
    "months": 1
  }'
200 OKResponse
{
  "calculator": "date/add@1",
  "result": {
    "result": "2026-02-28",
    "weekday": "Saturday"
  },
  "exactness": {},
  "precision": null,
  "inputs": {
    "start": "2026-01-31",
    "operation": "add",
    "years": 0,
    "months": 1,
    "weeks": 0,
    "days": 0,
    "hours": 0,
    "minutes": 0,
    "seconds": "0",
    "weekend": "sat_sun"
  },
  "formula": "months first (clamped to month end), then weeks and days, then elapsed time",
  "references": [
    {
      "title": "ISO 8601 date and time format",
      "url": "https://www.iso.org/iso-8601-date-and-time-format.html"
    },
    {
      "title": "IANA Time Zone Database",
      "url": "https://www.iana.org/time-zones"
    }
  ],
  "warnings": [
    {
      "code": "END_OF_MONTH_CLAMPED",
      "message": "Day 31 does not exist in February 2026; the last day of the month, 2026-02-28, was used."
    }
  ]
}

Ten business days

Requestcurl
curl https://api.curatedapi.com/v1/calc/date/add \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2026-10-16",
    "business_days": 10
  }'
200 OKResponse
{
  "calculator": "date/add@1",
  "result": {
    "result": "2026-10-30",
    "weekday": "Friday"
  },
  "exactness": {},
  "precision": null,
  "inputs": {
    "start": "2026-10-16",
    "operation": "add",
    "years": 0,
    "months": 0,
    "weeks": 0,
    "days": 0,
    "business_days": 10,
    "hours": 0,
    "minutes": 0,
    "seconds": "0",
    "weekend": "sat_sun"
  },
  "formula": "months first (clamped to month end), then weeks and days, then elapsed time",
  "references": [
    {
      "title": "ISO 8601 date and time format",
      "url": "https://www.iso.org/iso-8601-date-and-time-format.html"
    },
    {
      "title": "IANA Time Zone Database",
      "url": "https://www.iana.org/time-zones"
    }
  ],
  "warnings": []
}

Subtract a year from a leap day

Requestcurl
curl https://api.curatedapi.com/v1/calc/date/add \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2028-02-29",
    "years": 1,
    "operation": "subtract"
  }'
200 OKResponse
{
  "calculator": "date/add@1",
  "result": {
    "result": "2027-02-28",
    "weekday": "Sunday"
  },
  "exactness": {},
  "precision": null,
  "inputs": {
    "start": "2028-02-29",
    "operation": "subtract",
    "years": 1,
    "months": 0,
    "weeks": 0,
    "days": 0,
    "hours": 0,
    "minutes": 0,
    "seconds": "0",
    "weekend": "sat_sun"
  },
  "formula": "months first (clamped to month end), then weeks and days, then elapsed time",
  "references": [
    {
      "title": "ISO 8601 date and time format",
      "url": "https://www.iso.org/iso-8601-date-and-time-format.html"
    },
    {
      "title": "IANA Time Zone Database",
      "url": "https://www.iana.org/time-zones"
    }
  ],
  "warnings": [
    {
      "code": "END_OF_MONTH_CLAMPED",
      "message": "Day 29 does not exist in February 2027; the last day of the month, 2027-02-28, was used."
    }
  ]
}

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.