COUPNUM Function (Calligra Sheets)

• Introduced: Original introduction release not established. Presence in the checked release is not an introduction date.
• Available in source: Calligra Sheets 26.08.2, checked against first-party pinned source retrieved on October 18, 2026.
• Retired versus deprecated: Neither retirement nor deprecation is established; the function remains registered in this release.
• Verification: Selected formulas were executed in the Calligra Sheets 25.04.2 GUI on October 18, 2026. The native-results section lists those observations separately from independent calendar calculations and source analysis. 26.08.2 was source-checked only.
• Entry style: English names and semicolon separators. DATE constructors avoid locale-ambiguous date strings. Brackets in displayed syntax mark optional arguments and are not typed.

The KDE COUPNUM handbook documents the main interface. The source also implements an additional end-of-month option discussed below.

=COUPNUM(settlement; maturity; frequency[; basis[; eom]])

The source accepts nonzero integer divisors of 12, more than the ordinary 1/2/4 conventions. This guide does not promote extra frequencies as financially validated. Supply whole positive inputs deliberately; the source does not safely establish every negative or fractional case.

Additional source-supported option

The registration accepts three through five arguments. The fifth argument eom is a Boolean, default TRUE, controlling end-of-month handling. The older XML and handbook syntax document basis but omit this fifth option. Treat it as a released-source-supported Calligra detail, not a universally portable interface. Supply the fourth argument explicitly before setting the fifth.

Basis defaults to 0 and is accepted from 0 through 5. It is validated but does not affect the count calculation itself. The eom setting can affect a boundary count, as shown below. Unlike the other five coupon-family functions, COUPNUM exposes this fifth argument.

Use a fresh worksheet. Enter A1 “Settlement”, A2 “Maturity”, A3 “Frequency” and A4 “Basis”. Put =DATE(2025;3;15) in B1, =DATE(2026;12;31) in B2, 2 in B3 and 1 in B4. Keep formula outputs below the input block.

The regular semiannual schedule anchored to this end-of-month maturity has December 31 and June 30 coupon dates. Around settlement, the relevant dates are December 31, 2024 and June 30, 2025. Calendar subtraction gives 74 elapsed days and 107 remaining days, a total of 181 actual days in that period.

1. In B6 enter =COUPNUM(B1;B2;B3;B4).
2. Expect the number 4. Keep the output formatted as a count, not a date or percentage.
3. List the future coupons explicitly: June 30, 2025; December 31, 2025; June 30, 2026; December 31, 2026.
4. Count all four. The maturity coupon is included; the previous December 31, 2024 coupon is excluded.

The quarterly row has eight dates: March 31, June 30, September 30 and December 31 in 2025, then the corresponding four in 2026. Counting the dates explicitly avoids off-by-one reasoning based only on year differences.

Compare these two formulas:

=COUPNUM(DATE(2025;8;28);DATE(2026;2;28);2;0;TRUE())
=COUPNUM(DATE(2025;8;28);DATE(2026;2;28);2;0;FALSE())

The source-derived expected counts are 2 and 1, respectively. Maturity February 28, 2026 is at month end. With eom TRUE, the preceding semiannual coupon anchor is August 31, 2025, still after settlement, so August 31 and maturity both remain. With eom FALSE, the unpromoted August 28 anchor coincides with settlement and is excluded, leaving only maturity.

The native 25.04.2 test confirmed both counts, demonstrating the option’s practical importance. If using an imported workbook, verify that the fifth argument survives and means the same thing in the destination program. The other five COUP functions cannot be passed this fifth flag, so a custom FALSE-mode count should not be silently combined with their fixed-TRUE date schedule.

The body calculates a whole-month difference, aligns a candidate date in settlement’s month, optionally promotes that candidate to month end, then applies an integer-period calculation. It does not enumerate a supplied payment table or inspect issue-date information. Basis is validated but no day-count numerator enters that calculation.

For a regular coupon amount of 30, multiplying the main count 4 by 30 gives 120 of illustrative future coupon cash, excluding principal. That multiplication assumes every remaining payment has the same amount. It is not a present value: no discount rate or payment timing adjustment has been applied. Variable rates, missing payments and irregular stubs require a different model with explicit cash flows.

Settlement exactly on an intermediate coupon date excludes that coupon from the count. Settlement equal to maturity is rejected by the date-order validation instead of returning zero. A report covering matured instruments must handle that case before calling COUPNUM, rather than assuming a nonnegative count for every possible date pair.

• The source explicitly returns #VALUE! when settlement is on or after maturity, basis is outside 0–5, frequency is zero or frequency does not divide 12. These are source-predicted errors; their native cell display is not claimed here.
• Use positive frequencies. Some negative divisors pass the explicit validation but give invalid count semantics. COUPNUM does not use the shared coupon-date iteration; nevertheless, use only positive frequencies and do not interpret negative-input results as payment counts.
• Validate date inputs before calling the function. Invalid text dates, blanks, imported errors and fractional-selector coercion are outside the verified examples.
• The schedule is inferred backward from maturity at fixed month intervals. There is no issue date, first-coupon date, holiday calendar, business-day adjustment or irregular-stub argument. A computed date or count is not proof of the actual instrument’s payment schedule.
• End-of-month handling matters: when maturity is the last day of its month and end-of-month mode is enabled, generated coupon dates are moved to the last day of their respective months. Leap years and unequal month lengths therefore deserve explicit tests.
• Formula-name compatibility is not import/export verification. No workbook round trip or comparison with another spreadsheet engine has been performed.

• DATE constructs unambiguous date inputs.
• YEARFRAC is a separate year-fraction calculation, not a substitute for the coupon schedule.
• DAYS can support a date-difference cross-check when its argument order is observed.

The registered alternate name COM.SUN.STAR.SHEET.ADDIN.ANALYSIS.GETCOUPNUM invokes COUPNUM. It is the same function under another name; it does not select a different day-count method.

• Exact released implementation
• Shared schedule and validation helpers

These formulas were recalculated in Calligra Sheets 25.04.2 using a prepared ODS workbook, then saved by the application. The table records the native-saved results. Date-returning cells use ISO date formatting. Other examples in this guide remain independently calculated expectations or source analysis unless listed here.

Screenshot: Native Calligra Sheets 25.04.2. Selected cell B2 evaluates =COUPNUM(DATE(2025;3;15);DATE(2026;12;31);2;0) and shows 4.0000000000. Column B contains application results; column C shows the corresponding formula text. The final two rows show the end-of-month option changing the count from 2 to 1.

These selected observations establish 25.04.2 behavior for the listed formulas. They do not establish execution in 26.08.2, another locale or another spreadsheet product, nor do they validate an actual instrument’s contractual schedule.