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

Net present value (NPV) API

Net present value of a series of periodic cash flows at a discount rate.

POST https://api.curatedapi.com/v1/calc/finance/npv

Discounts each cash flow to today and adds them up: NPV = Σ CFₜ / (1 + r)ᵗ. By default the first cash flow happens now (t = 0) and is not discounted, the usual finance-textbook convention. Choose first_cash_flow_at = t1 to match spreadsheet NPV() functions, which discount the first value by one period.

Formula

NPV = Σ CFₜ / (1 + r)^(t + s), s = 0 (t0) or 1 (t1)
  • Amounts are plain numbers in any single currency; no currency conversion is done.

Inputs

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

InputTypeDescription
discount_rate_percent required decimal (string) Discount rate per period, in percent. Allowed: > -100 and <= 1000. Unit: percent.
cash_flows required list of decimal (string) Cash flows in time order, one per period. Money paid out is negative, money received is positive. 1 to 600 items. Each item: >= -1000000000000000 and <= 1000000000000000.
first_cash_flow_at t0 | t1
default t0
When the first cash flow happens. Options: t0: now, not discounted (finance convention); t1: at the end of the first period (spreadsheet NPV convention)
options.rounding half_even | half_up | half_down | up | down | ceiling | floor Rounding mode applied once to each result. Default half_even.
options.decimals integer Round results to this many digits after the decimal point.

Result

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

ResultTypeDescription
npvdecimal (string)Net present value. Unit: currency.
present_valueslist of stringPresent value of each cash flow.

Examples

Excel NPV example 1 (spreadsheet convention)

Requestcurl
curl https://api.curatedapi.com/v1/calc/finance/npv \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "discount_rate_percent": "10",
    "cash_flows": ["-10000", "3000", "4200", "6800"],
    "first_cash_flow_at": "t1"
  }'
200 OKResponse
{
  "calculator": "finance/npv@1",
  "result": {
    "npv": "1188.44",
    "present_values": [
      "-9090.91",
      "2479.34",
      "3155.52",
      "4644.49"
    ]
  },
  "exactness": {
    "npv": "rounded"
  },
  "precision": {
    "rounding": "half_even",
    "decimals": 2
  },
  "inputs": {
    "discount_rate_percent": "10",
    "cash_flows": [
      "-10000",
      "3000",
      "4200",
      "6800"
    ],
    "first_cash_flow_at": "t1"
  },
  "formula": "NPV = Σ CFₜ / (1 + r)^(t + s), s = 0 (t0) or 1 (t1)",
  "references": [
    {
      "title": "Microsoft Excel NPV function documentation (examples 1 and 2)",
      "url": "https://support.microsoft.com/en-us/excel/npv-function"
    }
  ],
  "warnings": []
}

Excel NPV example 2 (initial outlay now)

Requestcurl
curl https://api.curatedapi.com/v1/calc/finance/npv \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "discount_rate_percent": "8",
    "cash_flows": ["-40000", "8000", "9200", "10000", "12000", "14500"]
  }'
200 OKResponse
{
  "calculator": "finance/npv@1",
  "result": {
    "npv": "1922.06",
    "present_values": [
      "-40000.00",
      "7407.41",
      "7887.52",
      "7938.32",
      "8820.36",
      "9868.46"
    ]
  },
  "exactness": {
    "npv": "rounded"
  },
  "precision": {
    "rounding": "half_even",
    "decimals": 2
  },
  "inputs": {
    "discount_rate_percent": "8",
    "cash_flows": [
      "-40000",
      "8000",
      "9200",
      "10000",
      "12000",
      "14500"
    ],
    "first_cash_flow_at": "t0"
  },
  "formula": "NPV = Σ CFₜ / (1 + r)^(t + s), s = 0 (t0) or 1 (t1)",
  "references": [
    {
      "title": "Microsoft Excel NPV function documentation (examples 1 and 2)",
      "url": "https://support.microsoft.com/en-us/excel/npv-function"
    }
  ],
  "warnings": []
}

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.