Dividend Payout Ratio API: Coverage and Cuts

Coca-Cola has raised its dividend for 64 consecutive years. In 2025 it paid $8.78 billion in dividends and generated $7.41 billion of operating cash flow. Run the textbook dividend coverage ratio on those two numbers and one of the market's most famous dividend payers comes out at 0.84x, the same number a company paying its dividend with borrowed money would show. The ratio is computed correctly. The explanation behind it sits in one paragraph of the 10-K that a dividend screen never sees.

That gap is what this post is about. Most dividend history APIs we looked at return the calendar: ex-dividend date, payment date, amount. Whether a payout is sustainable takes three numbers lined up on the same fiscal period: cash dividends paid, net income, and operating cash flow. /api/earnings/dividend-history returns them as one series computed from each company's SEC filings, with the dividend payout ratio, the dividend coverage ratio, and year-over-year dividend growth already worked out. Below: what each field means and where it comes from in the XBRL, real responses for Coca-Cola, 3M, and Intel, the cases where a correct ratio still misleads, and a short screen that flags all of them.

Dividend history API vs. dividend calendar: two different questions

A dividend calendar answers what was declared and when: one row per declaration, keyed by ex-dividend date. That is what you need to track dividend income or to act around an ex-date, and StockFit serves it too. /api/earnings/dividend-date returns the next declared dividend for a stock (ex-date, record date, payment date, amount, and indicated annual dividend), and /api/earnings/upcoming-dividends lists every declared dividend with an ex-date up to 28 days ahead.

A dividend history in the fundamentals sense answers a different question: how well did the business fund it? That needs one row per fiscal year, with the cash actually paid set against the same year's earnings and operating cash flow. Those numbers sit in three places in a 10-K, which is why dividend endpoints that return the event list leave the join to you, and why many dividend investors end up pasting cash flow statements into spreadsheets. The calendar tells you a dividend is coming. The fiscal-year history tells you how it has been paid for. If you also need prices, splits, and the calendar on one schema, the stock market API for app developers page covers that wider surface.

The dividend payout ratio API call

One request per company and period type. Here is Coca-Cola, three fiscal years:

curl "https://api.stockfit.io/v1/api/earnings/dividend-history?symbol=KO&period=annual&limit=3" \
  -H "Authorization: Bearer $STOCKFIT_API_KEY"

[
  {
    "period": "2025-12-31",
    "fiscalYear": 2025,
    "fiscalPeriod": "FY",
    "dividendPerShare": 2.04,
    "totalDividendsPaid": 8779000000,
    "payoutRatio": 0.6698,
    "dividendCoverage": 0.8438,
    "dividendGrowth": 0.0517
  },
  {
    "period": "2024-12-31",
    "fiscalYear": 2024,
    "fiscalPeriod": "FY",
    "dividendPerShare": 1.94,
    "totalDividendsPaid": 8359000000,
    "payoutRatio": 0.7863,
    "dividendCoverage": 0.8141,
    "dividendGrowth": 0.0546
  },
  {
    "period": "2023-12-31",
    "fiscalYear": 2023,
    "fiscalPeriod": "FY",
    "dividendPerShare": 1.84,
    "totalDividendsPaid": 7952000000,
    "payoutRatio": 0.7422,
    "dividendCoverage": 1.4586,
    "dividendGrowth": 0.0453
  }
]

Five fields carry the dividend data, and each one traces to a specific place in the filing:

Every number on those three rows ties to Coca-Cola's own 10-K: $8,779 million and $8,359 million of dividends paid in 2025 and 2024, $2.04, $1.94, and $1.84 per share, and net income attributable to shareowners of $13,107 million, $10,631 million, and $10,714 million. The cash dividends come from the financing section of the cash flow statement, tagged in XBRL as us-gaap:PaymentsOfDividends or us-gaap:PaymentsOfDividendsCommonStock.

Use period=annual (the default) for payout and coverage. period=quarter exists, but cash dividends are lumpy inside a year because payment dates do not line up with quarter ends: Coca-Cola's fiscal 2025 quarters come out at $0.02, $0.51, $0.49, $1.02 per share, which only make sense summed back to the annual $2.04. On the free plan the endpoint returns the most recent fiscal year; Starter returns five fiscal years, and Stock or Pro return up to 40 per call.

Dividend payout ratio from SEC filings: dividends paid over net income

The dividend payout ratio is the share of a year's earnings paid out as dividends. Textbooks often write it per share, dividends per share over earnings per share; the endpoint uses the total-dollar form, which sidesteps any difference between the share count in EPS and the share count the dividend was paid on:

payoutRatio = cash dividends paid / net income
            = 8,779 / 13,107
            = 0.6698        (Coca-Cola, fiscal 2025, $ millions)

A payout ratio between 0 and 1 is the ordinary case. The interesting rows are the ones outside it:

Above 1.0 means the company paid out more than it earned that year. Intel's 182.8% for the fiscal year ended December 30, 2023 came as net income fell to $1.69 billion, while the per-share dividend was already being cut (more on that below). Costco's 122.7% for the fiscal year ended September 1, 2024 is not a sign of strain at all: it includes a $15-per-share special dividend paid January 12, 2024.

Below zero means a net loss, and the size of the negative number says nothing about the size of the dividend. Intel's -8.5% for fiscal 2024 sits against an $18.76 billion loss. 3M's -47.3% for 2023 sits against a $7.0 billion loss in the year its 10-K records pre-tax charges of $10.5 billion for its settlement of drinking-water claims by U.S. public water systems and $4.3 billion for the Combat Arms Earplugs settlement. Sort a universe ascending by payoutRatio without handling negatives and loss-making companies land at the top of your "lowest payout" list.

One sector caveat: REITs run real estate depreciation through net income, so payout ratios above 1.0 on net income are routine for them. That is a large part of why REITs report funds from operations (FFO), a measure that adds real estate depreciation back; judge a REIT dividend against its own FFO disclosure rather than this ratio.

Dividend coverage ratio: what Coca-Cola's 0.81 really means

The dividend coverage ratio flips the fraction and swaps the denominator: operating cash flow divided by cash dividends paid. Net income includes non-cash items such as depreciation, impairments, and remeasurements; operating cash flow does not, so coverage is the stricter test of whether the business itself generated the cash it paid out. At 1.0 or above, the year's operating cash funded the dividend. Below 1.0, part of it came from other sources, such as cash on hand or borrowing.

Coca-Cola's coverage sat between 1.40x and 1.74x from 2019 through 2023, then fell to 0.81x in 2024 and 0.84x in 2025, while the dividend kept rising:

A screen reads 0.81x as a dividend outrunning the business. The filing says something more specific. Coca-Cola's fiscal 2025 10-K (accession 0001628280-26-010047) explains both years in its cash flow discussion:

"Additionally, the activity in 2025 included $6.1 billion of the $6.2 billion final milestone payment for fairlife. The activity in 2024 included the $6.0 billion IRS Tax Litigation Deposit."

The fiscal 2024 10-K names the same deposit as the primary driver of that year's 41% drop in operating cash flow. Each payment is larger than the gap it opened: dividends exceeded operating cash flow by $1,554 million in 2024 and $1,371 million in 2025. Add the disclosed amounts back and coverage is 1.53x for 2024 and 1.54x for 2025, in line with 1.46x in 2023. That adjustment is our arithmetic, not a figure Coca-Cola reports, and the cash really did leave the company. The ratio was right; the explanation was one filing away, and the accession number tells you exactly which one.

Free cash flow coverage, with the receipts attached

Free cash flow coverage is stricter still, because it subtracts capital expenditures before comparing. The dividend endpoint does not return it, but /api/financials/cash-flow-statement has freeCashFlow alongside the accession number and filing date of the filing behind every fact:

const BASE = 'https://api.stockfit.io/v1/api';
const headers = { Authorization: `Bearer ${process.env.STOCKFIT_API_KEY}` };

const res = await fetch(`${BASE}/financials/cash-flow-statement?symbol=KO&period=annual&limit=3`, { headers });
const statements = await res.json();

for (const s of statements) {
  const { operatingCashFlow, freeCashFlow, cashDividendsPaid } = s.facts;
  const accession = Object.keys(s.sources).find(a => s.sources[a].facts.cashDividendsPaid);
  console.log(s.fiscalYear, {
    ocfCoverage: +(operatingCashFlow / cashDividendsPaid).toFixed(2),
    fcfCoverage: +(freeCashFlow / cashDividendsPaid).toFixed(2),
    accession,
    filed: s.sources[accession].dateFiled,
  });
}

2025 { ocfCoverage: 0.84, fcfCoverage: 0.6, accession: '0001628280-26-010047', filed: '2026-02-20' }
2024 { ocfCoverage: 0.81, fcfCoverage: 0.57, accession: '0000021344-25-000011', filed: '2025-02-20' }
2023 { ocfCoverage: 1.46, fcfCoverage: 1.23, accession: '0000021344-24-000009', filed: '2024-02-20' }

Free cash flow covered the dividend 1.23x in 2023 and 0.57x and 0.60x in the two years with one-time payments. Paste an accession into /api/filings/search-by-accession-number or EDGAR and you are one click from the paragraph quoted above.

One exception to all of this: banks and broker-dealers. Their operating cash flow swings by tens of billions with trading assets and loans held for sale, and it turns negative in some ordinary years (JPMorgan Chase's was -$42.0 billion in 2024 and -$147.8 billion in 2025), so dividendCoverage carries no signal there. Use the payout ratio for financials.

How to detect dividend cuts and suspensions

dividendGrowth is the year-over-year change in cash dividends per share, so a dividend cut shows up as a negative number. Here are three payers over ten fiscal years, each named by its own fiscal year (Intel's years end on the last Saturday of December):

Intel cut its quarterly dividend from $0.365 to $0.125 in February 2023, paid at the new rate from June 1, 2023, then suspended it from the fourth quarter of 2024 (announced August 1, 2024; the last $0.125 was paid September 1, 2024). Because dividendPerShare is cash paid during the fiscal year, those two decisions land across three fiscal years: $1.46 in 2022, $0.74 in 2023 (-49.5%), $0.37 in 2024 (-49.3%), and $0 in the fiscal year ended December 27, 2025, with a dividendGrowth of -1.

3M's reset was a policy change after the April 1, 2024 spin-off of Solventum: the quarterly dividend went from $1.51 to $0.70 starting with the June 12, 2024 payment. Fiscal 2024 still contained one payment at the old rate, so cash per share fell 39.8% in 2024 to $3.60, and another 19.2% in 2025 to $2.91.

Two rules fall out of those two histories:

• A cut spreads across two fiscal years in cash-basis data. Compare two-year changes before deciding a payer has stabilized, and expect the second year of a reset to look like a second cut.
• A stock split cuts the per-share figure without cutting a dollar of payout. The endpoint rescales per-share history using the split events recorded in /api/company/stock-splits (splitAdjust=true by default; our guide to detecting stock splits in historical data covers how those events are found). The cheap, robust check works either way: a real cut lowers totalDividendsPaid too, a split does not.

Null versus zero

The difference between null and 0 is information, not formatting. Amazon, which has never paid a dividend, returns null for every field in every fiscal year. Meta returns 0 for 2022 and 2023: its filings report a zero PaymentsOfDividends fact for the years before it initiated a $0.50 quarterly dividend, announced February 1, 2024 and first paid March 26, 2024. Intel returns 0 for fiscal 2025, its first full year after the suspension.

So 0 means the filer reported paying nothing, and null means the curated cash flow statement holds no dividends-paid fact for that period. Before you treat a null as "never paid," check /api/financials/as-reported for the same period: filers can tag dividends under other US GAAP concepts than the two the curated line maps.

What a cash-basis dividends-paid figure includes

dividendPerShare is derived from cash, not copied from the dividend declaration, which makes it consistent with the payout and coverage math but means it can include more than the regular common dividend:

• Special dividends. Costco's figure for the fiscal year ended September 1, 2024 is $20.37 because it includes the $15 special dividend paid January 12, 2024. The jump is real cash, but it is not a new run rate.
• Preferred dividends and noncontrolling interests. The US GAAP taxonomy defines us-gaap:PaymentsOfDividends as cash distributions "to common shareholders, preferred shareholders and noncontrolling interests." When a filer tags only that total, the per-share figure includes more than the common dividend. PaymentsOfDividendsCommonStock, when a filer uses it, is common stock only.
• Payment timing. A fiscal year can hold an extra or a missing quarterly payment when payment dates sit near the year-end, which moves dividendGrowth without any change in the dividend rate.

The cross-check is the filer's own per-share number. Companies tag either a declared or a cash-paid per-share concept, and /api/financials/as-reported keeps that fact verbatim. Here is Coca-Cola's fiscal 2025, trimmed to the two dividend facts:

{
  "period": "2025-12-31",
  "fiscalYear": 2025,
  "facts": {
    "us-gaap:PaymentsOfDividends": 8779000000,
    "us-gaap:CommonStockDividendsPerShareCashPaid": 2.04
  }
}

The derived $2.04 matches the filer's $2.04 to the cent. XBRL US's guidance on dividend disclosures in XBRL explains the declared versus paid concepts; when the derived number and the filer's own differ by more than a cent or two, one of the three items above is the place to look.

A dividend safety screen in under 40 lines of JavaScript

Put the rules together and you have a screen that flags every case in this post. It pulls four fiscal years per company and checks the latest three: missing or zero dividends, a payout ratio outside 0 to 1, operating cash flow below dividends, and a cut confirmed by total cash paid.

const BASE = 'https://api.stockfit.io/v1/api';
const headers = { Authorization: `Bearer ${process.env.STOCKFIT_API_KEY}` };

async function dividendHistory(symbol) {
  const res = await fetch(`${BASE}/earnings/dividend-history?symbol=${symbol}&period=annual&limit=4`, { headers });
  if (!res.ok) {
    throw new Error(`${res.status} for ${symbol}`);
  }
  return res.json(); // newest fiscal year first
}

function flags(year, prior) {
  const out = [];
  if (year.totalDividendsPaid == null) {
    out.push('no dividends-paid fact');
  } else if (year.totalDividendsPaid === 0) {
    out.push('paid zero');
  }
  if (year.payoutRatio != null && (year.payoutRatio < 0 || year.payoutRatio > 1)) {
    out.push('payout outside 0-100%');
  }
  if (year.dividendCoverage != null && year.dividendCoverage < 1) {
    out.push('operating cash flow below dividends');
  }
  // A real cut lowers the total cash paid too; a stock split only lowers the per-share figure.
  if (year.dividendGrowth < 0 && prior?.totalDividendsPaid > year.totalDividendsPaid) {
    out.push('dividend cut');
  }
  return out;
}

for (const symbol of ['KO', 'MMM', 'INTC', 'AMZN']) {
  const years = await dividendHistory(symbol);
  for (let i = 0; i < 3 && i < years.length; i++) {
    const found = flags(years[i], years[i + 1]);
    console.log(symbol.padEnd(5), years[i].fiscalYear, found.join('; ') || 'ok');
  }
}

Run against the live API, it prints:

KO    2025 operating cash flow below dividends
KO    2024 operating cash flow below dividends
KO    2023 ok
MMM   2025 dividend cut
MMM   2024 operating cash flow below dividends; dividend cut
MMM   2023 payout outside 0-100%
INTC  2025 paid zero; dividend cut
INTC  2024 payout outside 0-100%; dividend cut
INTC  2023 payout outside 0-100%; dividend cut
AMZN  2025 no dividends-paid fact
AMZN  2024 no dividends-paid fact
AMZN  2023 no dividends-paid fact

Every flag is real, and every one has an explanation in a filing. Coca-Cola's two coverage flags are the tax deposit and the fairlife payment. 3M's 2023 payout flag is the settlement-driven loss, and its 2024 coverage flag lines up with what its 2024 10-K describes as approximately $4.6 billion of payments for PFAS-related environmental liabilities and the Combat Arms Earplugs settlement. The cut flags are 3M's reset and Intel's cut and suspension, and Amazon's nulls mean what they look like. A screen narrows the list; the filing behind the accession number tells you which flags matter.

Two notes for production use. For backtests, join each fiscal year to the cash flow statement's dateFiled, the original filing date, so Coca-Cola's 2024 coverage only becomes visible to a simulation on February 20, 2025; our post on point-in-time data for backtesting covers why that matters. And for a balance-sheet view next to the dividend, the financial health score API adds an Altman Z-Score and Piotroski F-Score per company, from the same filings, with net income cross-checkable against /api/financials/income-statement.

Get a free API key and run the screen on your own watchlist. The free plan returns the latest fiscal year, enough for the payout, coverage, and null checks; the cut check compares two fiscal years, which starts at Starter.

StockFit provides data, not investment advice. Nothing here is a recommendation to buy or sell any security.

FAQ