Dividend calculator

Zero shares outstanding is rejected with invalid_input because it cannot be the denominator.

What dividend per share and yield mean, and how cash becomes a rate

This endpoint does not fetch filings or live quotes. It applies the definitions you supply so homework keys, landing-page widgets, and automation share one auditable amount and rate.

Input contract, response shape, and error behaviour

Optional decimals is an integer from zero through twelve (default six) controlling half-up rounding on the per-share amount and both yield fields. Shares outstanding is the field the product contract singles out: a zero share count is never silently replaced with one, and a missing count is not treated as zero. Failed validation does not consume balance, which keeps exploratory scripts cheap when developers intentionally send a zero share count to confirm the error path. POST a JSON body with three required finite numbers. total_dividends (aliases total_dividend, dividends, dividend_paid, and cash_dividends) is the aggregate cash dividend in currency units. It must be finite and greater than or equal to zero so a firm that paid nothing is allowed. shares_outstanding (aliases shares, number_of_shares, outstanding_shares, and shares_issued) is the share count used as the per-share denominator and must be a finite number strictly greater than zero. share_price (aliases price, stock_price, market_price, and last_price) is the quote in the same currency as the dividend and must be a finite number strictly greater than zero. On success the body echoes total_dividends, shares_outstanding, and share_price, then dividend_per_share as the cash amount per share, dividend_yield as a percent, dividend_yield_decimal as the equivalent fraction, and a formula string restating dividend per share equals total dividends over shares outstanding and yield equals dividend per share over share price. Example: two billion of total dividends, five hundred million shares, and a fifty-dollar price returns dividend_per_share four, dividend_yield eight, and dividend_yield_decimal zero point zero eight. Missing fields, non-finite values, a negative total, or a share count or price that is zero or negative fail with invalid_input naming the field and are not billed. Prefer plain JSON numbers over strings with currency symbols or percent signs; numeric strings are accepted only when they match a strict finite number pattern without commas or labels. Pricing is a fixed $0.002 per successful call with unit item.

Where a dividend calculator earns its keep

Educators and LMS platforms need an oracle for the definition question that asks students to compute dividend per share from total dividends and shares outstanding, including the zero-cash case, without a market-data terminal. Content teams can contrast trailing yield with forward yield on the same share count so readers see why two percentages can describe one ticker when the indicated rate differs from last year's cash. Use this capability when you already have total cash, a share count, and a price; if you have annual coupon dollars and a bond face amount, use a coupon-rate calculator instead of this equity dividend definition. Back-office files often store total dividends paid, shares outstanding, and last price in separate columns; a deterministic endpoint recovers DPS and yield without a spreadsheet cell that someone might later rewrite as a payout ratio by dividing by earnings. Integrators wire the endpoint into notebooks, workflow tools, or edge workers to pin goldens whenever a portfolio extract changes the stored cash, the diluted share count, or the quote. Keep shares_outstanding and share_price strictly positive, pin the rounded dividend_per_share and dividend_yield fields in tests, and you get reproducible cash amounts and yields for widgets, classrooms, and production without standing up an equity-research library of your own.