Documentation/Calc Functions/CUMPRINC

    From The Document Foundation Wiki
    Other languages:

    Function name:

    CUMPRINC

    Category:

    Financial Analysis

    Summary:

    Calculates the total or cumulative capital (principal) repaid during a time interval, for a fixed-rate loan that is based on a specified number of regular payments over a defined term.

    While the regular payments are always for the same amount, the proportion of interest and capital repaid at each period varies over the duration of the loan. The PMT function calculates the fixed periodic payment (capital and interest), while the PPMT function calculates the capital element of the payment for a specified period and the IPMT function calculates the interest element of the corresponding payment.

    CUMPRINC calculates the total capital repaid between a specified start period and a specified end period. This is equivalent to summing the PPMT values for each period during that interval.

    Syntax:

    CUMPRINC(Rate; NPER; PV; S; E; Type)

    Returns:

    Returns a negative real number, which is the total value of the capital elements of the payments made within the specified time interval. The number returned is in the same currency unit as the specified present value, and by default is formatted in a locale-dependent currency format.

    Arguments:

    Rate is a real number (expressed as a percentage, such as 2.5%, or a decimal fraction, such as 0.025), or a reference to a cell containing that number, which is the periodic interest rate. It is common for interest rates to be quoted annually and, where necessary, care should be taken to convert such values to be compatible with the length of your payment period.

    NPER is a positive real number, or a reference to a cell containing that number, which is the number of payment periods in the term.

    PV is a positive real number, or a reference to a cell containing that number, which is the present value of the amount borrowed.

    S is a positive integer, or a reference to a cell containing that integer, which is the first period for which the capital element of the payment is to be summed.

    E is a positive integer, or a reference to a cell containing that integer, which is the last period for which the capital element of the payment is to be summed.

    Type is a logical value, or a reference to a cell containing a logical value, which determines whether the due date is at the beginning or end of a payment period. If Type is set to 0 or FALSE, then the function assumes the end of the payment period. If Type is set to 1 or FALSE, then the function assumes the start of the payment period.

    • If any argument is non-numeric, then CUMPRINC reports a #VALUE! error.
    • If Rate is less than or equal to 0.0, then CUMPRINC reports an invalid argument error (Err:502).
    • If PV is less than or equal to 0.0, then CUMPRINC reports an invalid argument error (Err:502).
    • If either of S or E is a non-integer value, then CUMPRINC truncates it to an integer value. Note that non-integer values of NPER are not truncated.
    • If after any truncation S is less than 1.0, then CUMPRINC reports an invalid argument error (Err:502).
    • If after any truncation E is less than S or greater than NPER, then CUMPRINC reports an invalid argument error (Err:502).
    • If Type is not equal to 0, FALSE, 1, or TRUE, then CUMPRINC reports an invalid argument error (Err:502).

    Additional details:

    • The purpose of CUMPRINC can be expressed in the following formula:
    [math]\displaystyle{ \text{CUMPRINC}(Rate;\:NPER;\:PV;\:S;\:E;\:Type)~=~\sum_{p=S}^{E}~\text{PPMT}(Rate;\:p;\:NPER;\:PV;\: 0;\:Type) }[/math]

    Examples:

    Note that the formatting of the return values given in the following examples assume the English (USA) locale.

    Simple example with multiple calls to CUMPRINC

    Lucas decides to borrow $20,000 over a period of 6 years at an annual interest rate of 8%. There is no cash balance remaining at the end of the loan and payments are due at the end of each year. The following table shows the capital components of his repayments.

    Data for examples of CUMPRINC function
    A B C D E F G H
    1 Loan amount $20,000
    2 Annual rate 8%
    3
    4 End Year
    5 1 2 3 4 5 6
    6 Start Year 1 -$2,726.31 -$5,670.72 -$8,850.69 -$12,285.05 -$15,994.16 -$20,000.00
    7 2 -$2,944.41 -$6,124.38 -$9,558.74 -$13,267.85 -$17,273.69
    8 3 -$3,179.97 -$6,614.33 -$10,323.44 -$14,329.28
    9 4 -$3,434.36 -$7,143.47 -$11,149.31
    10 5 -$3,709.11 -$7,714.95
    11 6 -$4,005.84

    Cells C6:H11 show the capital components paid during all possible time periods. The possible start years are listed in cells B6:B11, while the possible end years are listed in cells C5:H5. Cells C6:H11 contain formulas as follows:

    • Cell C6 contains the formula =CUMPRINC($B$2; $B$11; $B$1; $B6; C$5; 0), showing the capital component of the first year’s payment (the same value would be returned by the formula =PPMT($B$2; $B6; $B$11; $B$1; 0)). Cell D7 contains the formula =CUMPRINC($B$2; $B$11; $B$1; $B7; D$5; 0), showing the capital component of the second year's payment. Cells E8, F9, G10, and H11 contain corresponding formulas to calculate the capital component of each subsequent year’s payment.
    • Cell H6 shows the value -$20,000.00 and this is the total capital repaid during the six-year term of the loan.
    • Cell D6 contains the formula =CUMPRINC($B$2; $B$11; $B$1; $B6; D$5, 0), showing the sum of the capital components of the first and second year's payments (the same value would be returned by the formula =C6+D7). Cell E6 contains the formula =CUMPRINC($B$2; $B$11; $B$1; $B6; E$5; 0), showing the sum of the capital components of the first, second and third year’s payments. Cells F6, G6, and H6 contain corresponding formulas to calculate the capital components of payments made in longer time periods that start with year 1.
    • Cells E7:H7 contain appropriate calls to CUMPRINC to calculate the capital components of payments made in multiple year time periods that start with year 2.
    • Cells F8:H8 contain appropriate calls to CUMPRINC to calculate the capital components of payments made in multiple year time periods that start with year 3.
    • Cells G9:H9 contain appropriate calls to CUMPRINC to calculate the capital components of payments made in multiple year time periods that start with year 4.
    • Cell H10 contains an appropriate call to CUMPRINC to calculate the capital components of payments made in the multiple year time period that covers years 5 and 6.
    • The cells colored dark grey represent cases where the start month would be greater than the end month, a condition that would result in an error from the CUMPRINC function.

    Additional examples

    Formula Description Returns
    =CUMPRINC(5.5%/12; 24; 5000; 4; 6; 1) Here the function calculates the total capital element of the payments for months 4 to 6, for a loan of 5,000 currency units at an annual interest rate of 5.5% (5.5%/12 per month), with a term of 2 years (24 months). Payments are due at the beginning of each month. The capital element of the payments for months 4-6 is calculated by CUMPRINC as 600.88 currency units and this is returned as a negative value. -$600.88
    =CUMPRINC(5.5%/12; 24; 5000; 4; 6; 0) Here the function calculates the total capital element of the payments for months 4 to 6, for a loan of 5,000 currency units at an annual interest rate of 5.5% (5.5%/12 per month), with a term of 2 years (24 months). Payments are due at the end of each month. The capital element of the payments for months 4-6 is calculated by CUMPRINC as 603.63 currency units and this is returned as a negative value. -$603.63

    Related LibreOffice functions:

    CUMIPMT

    CUMIPMT_ADD

    CUMPRINC_ADD

    PPMT

    ODF standard:

    Section 6.12.12, part 2

    Related (or similar) Excel functions:

    CUMPRINC