Credit utilization calculator

A total credit limit of zero is rejected with invalid_input and is not billed, because dividing by zero cannot define a utilization rate.

What credit utilization means and how the two totals become a percent

In symbols, utilization_ratio equals total_balance divided by total_credit_limit, and utilization_percent is that ratio times one hundred. This calculator is the two-number form of that identity. An unused card with a zero balance and a four-thousand limit still enlarges total_credit_limit and lowers the overall percent; closing that card later can raise utilization overnight even though you borrowed nothing new. A worked check is a combined balance of two thousand on a combined limit of six thousand: the ratio is one third, and utilization_percent is about 33.33. That sits just above the common 30 percent guideline that many counselors cite before a mortgage pull. When the combined balance exceeds the combined limit the wallet is over-limit, the percent goes past one hundred, available_credit is zero, and over_limit_amount records the excess.

Input contract, response shape, and error behaviour

POST a JSON body with two required finite numbers. total_balance is the combined outstanding revolving balance in one currency unit; aliases balance, balances, total_balances, and outstanding map to the same field so a statement extract can keep its column names. total_credit_limit is the combined revolving credit limit in that same currency; aliases credit_limit, limit, total_limit, and creditLimit are accepted. Each numeric field may arrive as a JSON number or a numeric string. Missing fields, empty strings, and non-finite values fail with invalid_input naming the field. total_balance must be greater than or equal to zero: a zero balance is a legitimate unused-credit case and returns utilization_percent of zero rather than an error. A negative balance is rejected. total_credit_limit must be strictly greater than zero. A balance larger than the limit is allowed: the wallet is over-limit, utilization_percent exceeds one hundred, over_limit is true, available_credit is zero, and over_limit_amount records the surplus instead of clamping the percent. On success the body echoes the two totals rounded half-up to two decimal places, then reports utilization_ratio rounded to six places, utilization_percent rounded to two places, available_credit, over_limit_amount, the over_limit boolean, and a formula string restating the identity. Example: two thousand of combined balances on a ten-thousand combined limit yields a utilization of twenty percent, eight thousand of available credit, and over_limit false. Pair the JSON with your own list of which accounts you summed — this endpoint divides the two numbers you send; it does not pull a bureau file, age a score, or reconstruct per-card rows.

Where a credit utilization calculator earns its keep

Pair it with your own bureau extract when the question is what the bureaus already see, and use this calculator when the question is what two known revolving totals imply right now. Credit counselors and nonprofit coaches use the two-number endpoint when a client already has statement totals in hand and only wants the percent, remaining room, and whether the wallet is over-limit, without typing every card. Exam-prep and classroom units need a deterministic oracle that treats a zero limit as invalid_input rather than a divide-by-zero, allows over-limit percents above one hundred, and returns both the ratio and the percent. Keep requests small and pin utilization_percent plus available_credit in tests. This tool does not pull a credit report, does not age a FICO-style score, and does not model authorized-user tradelines, charge-offs, or the difference between reported statement balances and today's live balance. Keep total_credit_limit strictly positive, send both numbers in one currency, and you get a reproducible utilization percent for landing pages, LMS plugins, and edge workers without standing up a per-card engine of your own.