{
  "openapi": "3.0.3",
  "info": {
    "title": "Percentage, Tip and Discount Calculator API",
    "version": "1.5.1",
    "description": "Percentages, tips and bill splits, discounts and GPA. Percentage calculations, tip and bill split, discount and sale price, and GPA from grades and credits. Nothing you send is stored. One X-API-Key header authenticates every call, and the same key works across every FreeDailyPro API. Every 4xx response is documented and none of them is billed.",
    "contact": {
      "name": "FreeDailyPro",
      "url": "https://www.freedailypro.com/developers",
      "email": "support@freedailypro.com"
    },
    "termsOfService": "https://www.freedailypro.com/terms",
    "x-logo": {
      "url": "https://www.freedailypro.com/favicon.ico"
    }
  },
  "servers": [
    {
      "url": "https://api.freedailypro.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer hub, plans and MCP setup",
    "url": "https://www.freedailypro.com/developers"
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "tags": [
    {
      "name": "Everyday Math",
      "description": "Percentages, tips and bill splits, discounts and GPA."
    }
  ],
  "paths": {
    "/v1/converters/percentage": {
      "post": {
        "summary": "Calculate a percent of a number, what percent one number is of another, a change, percentage points or basis points, with the working",
        "operationId": "convertersPercentage",
        "description": "Eight percentage operations in one endpoint, each returning the answer in 'result' and the working in 'steps' (an ordered list of { label, formula, inputs, result }). 'a' and 'b' mean different things per operation: percentageOf (a is the part, b the whole: what percent a is of b), whatIsPercentOf (a percent of b), percentChange (change from a to b, measured against the size of a), percentagePoints (a and b are themselves percentages: the change in percentage points, plus 'relativeChangePct'; 10 to 12 is +2 points and +20%), changeByPercent (raise or lower the number a by b percent; 'direction' increase or decrease), originalValue (the value before a was raised or lowered by b percent), percentDifference (symmetric difference of a and b against their average) and solveNumber (the number that a percent of gives b). 'unit' percent (default), permille or bps (basis points; 25 bps of 10,000 is 25) applies to percentageOf, whatIsPercentOf and solveNumber. Who calls it: pricing and discount engines, finance dashboards that report rate changes in points and basis points, invoicing and reporting tools that need the working shown next to a figure, and chatbots or MCP agents that must not do arithmetic themselves. Worked example: POST {\"operation\":\"percentageOf\",\"a\":15,\"b\":240} returns result 6.25 with two steps (15 / 240 = 0.0625, then x 100 = 6.25%). Integration scenario: a loan tool shows 'your rate rose from 6.5% to 6.75%'; call percentagePoints with a 6.5 and b 6.75 to get +0.25 points (25 bps as whatIsPercentOf with unit bps) and a relative change of +3.85%. These are the same functions the FreeDailyPro website calculator runs, so the site and the API always agree. Pure arithmetic: no external data, no tax year, nothing to update. Division by zero (a whole of 0, a starting value of 0, a percent of 0 for solveNumber), a decrease of more than 100%, non-finite numbers, and a unit or direction sent with an operation that does not use it are rejected with a 400 and a plain-words message; the API never returns NaN, Infinity or null. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Everyday Math"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "operation": {
                    "type": "string",
                    "enum": [
                      "percentageOf",
                      "whatIsPercentOf",
                      "percentChange",
                      "percentagePoints",
                      "changeByPercent",
                      "originalValue",
                      "percentDifference",
                      "solveNumber"
                    ],
                    "description": "percentageOf: what percent a is of b. whatIsPercentOf: a percent of b. percentChange: change from a to b. percentagePoints: both a and b are percentages; returns the change in percentage points. changeByPercent: raise or lower the number a by b percent. originalValue: the value before a was raised or lowered by b percent. percentDifference: symmetric difference of a and b. solveNumber: the number that a percent of gives b."
                  },
                  "a": {
                    "type": "number",
                    "description": "First value. What it means depends on the operation (see operation)."
                  },
                  "b": {
                    "type": "number",
                    "description": "Second value. What it means depends on the operation (see operation)."
                  },
                  "unit": {
                    "description": "percent (default), permille (parts per thousand) or bps (basis points). Only for percentageOf, whatIsPercentOf and solveNumber.",
                    "type": "string",
                    "enum": [
                      "percent",
                      "permille",
                      "bps"
                    ]
                  },
                  "direction": {
                    "description": "Only for changeByPercent and originalValue. Default increase.",
                    "type": "string",
                    "enum": [
                      "increase",
                      "decrease"
                    ]
                  }
                },
                "required": [
                  "operation",
                  "a",
                  "b"
                ],
                "additionalProperties": false
              },
              "example": {
                "operation": "percentageOf",
                "a": 15,
                "b": 240
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Percentage calculator client and server side from freedailypro",
                  "operation": "percentageOf",
                  "result": 6.25,
                  "steps": [
                    {
                      "label": "Divide the part by the whole",
                      "formula": "part / whole",
                      "inputs": {
                        "part": "15",
                        "whole": "240"
                      },
                      "result": "0.0625"
                    },
                    {
                      "label": "Multiply by 100",
                      "formula": "ratio x 100",
                      "inputs": {
                        "ratio": "0.0625"
                      },
                      "result": "6.25%"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "A missing or non-numeric a or b, an unknown operation, unit or direction, a unit or direction sent to an operation that does not use it, or input with no answer (division by zero, a decrease over 100%); the body says which Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/tip": {
      "post": {
        "summary": "Calculate the tip, total and per-person amount, compare percentages, split unevenly, apply service presets or work out the tip left",
        "operationId": "convertersTip",
        "description": "Send 'bill' and 'tipPercent' (and 'people' to split evenly) for the tip, the total and the per-person amount, with a 'steps' array that shows the working. Optional fields: 'tax' (added to the total; 'tipOnPreTax' true, the default with extras, works the tip on the bill before tax, false works it on bill plus tax); 'comparePercents' (up to 10 percentages; default 10, 15, 18, 20, 25) returns 'comparison' with the tip, total and per-person amount at each; 'service' (restaurant, delivery, bar, salon, taxi, housekeeping) returns the usual range and a one-line norm and supplies the suggested percentage when tipPercent is not sent (housekeeping suggests a flat amount per night); 'currency' (a three-letter code such as JPY) returns 'customs' for that currency's main country (expected, optional, included or not customary); 'items' (one amount per person) returns 'uneven': each person pays their own amount plus a pro-rata share of tax and tip, shares add up to the total exactly; 'paid' (the total that was paid) returns 'impliedTip' and 'impliedTipPercent'. Who calls it: restaurant and delivery apps, bill-splitting and expense apps, travel guides that show local tipping customs next to a calculator, point-of-sale prompts, and chatbots or MCP agents. Worked examples: {\"bill\":50,\"tipPercent\":18} returns a comparison with 15% at tip 7.5, total 57.5 and 25% at tip 12.5, total 62.5; {\"bill\":90,\"tipPercent\":20,\"items\":[20,30,40]} returns uneven shares 24, 36 and 48 (total 108); {\"bill\":50,\"paid\":60} returns impliedTipPercent 20. Integration scenario: a bill-splitting app lets each friend enter what they ordered and calls the endpoint once with 'items' and the tax; every person's exact amount comes back and the amounts add up to the cent. Service ranges are common US etiquette guidance (consumer etiquette guides such as the Emily Post Institute) and country notes are general customs; both are conventions, not rules, and they are held in one table file shared with the FreeDailyPro website calculator, reviewed by FreeDailyPro when customs change. The arithmetic is in cents so shares always add up. Requests with no answer (no tipPercent, service or paid; a paid amount below the bill plus tax; items whose count differs from people; a bill of 0 in reverse mode) are rejected with a 400 and a plain-words message. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Everyday Math"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bill": {
                    "type": "number",
                    "minimum": 0,
                    "description": "The bill before tip (and before tax when 'tax' is sent separately)."
                  },
                  "tipPercent": {
                    "description": "Tip percentage. Required unless 'service' or 'paid' is sent.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "people": {
                    "description": "Number of people splitting the bill. Default 1 (or the length of 'items').",
                    "type": "number",
                    "minimum": 1,
                    "maximum": 100
                  },
                  "tax": {
                    "description": "Tax amount. Added to the total; the tip is on the pre-tax bill unless tipOnPreTax is false.",
                    "type": "number",
                    "minimum": 0
                  },
                  "tipOnPreTax": {
                    "description": "Whether the tip is worked out on the bill before tax (true, the default when extras are used) or on bill plus tax (false).",
                    "type": "boolean"
                  },
                  "comparePercents": {
                    "description": "Percentages to compare at once. Default 10, 15, 18, 20 and 25. Returns 'comparison' with the tip, total and per-person amount at each.",
                    "maxItems": 10,
                    "type": "array",
                    "items": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    }
                  },
                  "items": {
                    "description": "Uneven split: each person's own amount, one per person. Each pays their own amount plus a pro-rata share of tax and tip; shares add up exactly.",
                    "maxItems": 100,
                    "type": "array",
                    "items": {
                      "type": "number",
                      "minimum": 0
                    }
                  },
                  "paid": {
                    "description": "Reverse mode: the total that was paid. Returns impliedTip and impliedTipPercent for the bill (and tax).",
                    "type": "number",
                    "minimum": 0
                  },
                  "service": {
                    "description": "A service preset: returns its usual range and note, and uses its suggested percentage (or flat amount for housekeeping) when tipPercent is not sent.",
                    "type": "string",
                    "enum": [
                      "restaurant",
                      "delivery",
                      "bar",
                      "salon",
                      "taxi",
                      "housekeeping"
                    ]
                  },
                  "currency": {
                    "description": "A three-letter currency code, for example JPY. Returns 'customs': whether tipping is customary in that currency's main country.",
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3
                  }
                },
                "required": [
                  "bill"
                ],
                "additionalProperties": false
              },
              "example": {
                "bill": 86.5,
                "tipPercent": 18,
                "people": 3
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Tip calculator client and server side from freedailypro",
                  "result": {
                    "tipAmount": 15.57,
                    "total": 102.07,
                    "perPerson": 34.02333333333333,
                    "steps": [
                      {
                        "label": "Amount the tip is based on",
                        "formula": "bill (before tax)",
                        "inputs": {
                          "bill": "86.50",
                          "tax": "0.00"
                        },
                        "result": "86.50"
                      },
                      {
                        "label": "Tip",
                        "formula": "base x tip % / 100",
                        "inputs": {
                          "base": "86.50",
                          "tip %": "18%"
                        },
                        "result": "15.57"
                      },
                      {
                        "label": "Total",
                        "formula": "bill + tax + tip",
                        "inputs": {
                          "bill": "86.50",
                          "tax": "0.00",
                          "tip": "15.57"
                        },
                        "result": "102.07"
                      },
                      {
                        "label": "Per person",
                        "formula": "total / people, shared out in cents so the shares add up exactly",
                        "inputs": {
                          "total": "102.07",
                          "people": 3
                        },
                        "result": "34.03 or 34.02"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing tipPercent (with no service or paid), a value out of range, items whose length differs from people, a paid amount below the bill plus tax, a bill of 0 in reverse mode, or an unknown service; the body says which Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/discount": {
      "post": {
        "summary": "Calculate the sale price and savings from a discount percentage or a sale price",
        "operationId": "convertersDiscount",
        "description": "Three ways in. (1) 'originalPrice' + 'discountPercent': the first version, unchanged (discountAmount, finalPrice, savingsPercent). (2) 'originalPrice' + 'salePrice': the discount percentage as before, plus 'amountOff' (the same saving as a fixed amount) and a plain-words 'note'. (3) NEW: 'originalPrice' + 'discounts', 1 to 5 entries of { type: percent or amount, value } applied one after the other IN THE ORDER SENT, each on the price left by the one before: 100 with 20% then 15 off is 65, but 15 off then 20% is 68. Optional 'taxPercent' is added on the discounted price. Returns 'discounts' (each with priceBefore, amountOff, priceAfter), 'finalPrice', 'totalSaved', 'effectivePercent', 'tax' and 'totalWithTax' when tax is sent, and a 'steps' array that shows the working. A discount that would take the price below 0 (for example 120 off a price of 100) is rejected; exactly 0 is allowed. Who calls it: shopping and coupon-stacking tools, price-comparison sites, checkout and promo-engine previews, small-retailer price tools, and chatbots or MCP agents. Worked examples: {\"originalPrice\":100,\"discounts\":[{\"type\":\"percent\",\"value\":20},{\"type\":\"amount\",\"value\":15}]} returns finalPrice 65, totalSaved 35 and effectivePercent 35; the same discounts in the other order with taxPercent 8 returns finalPrice 68, tax 5.44, totalWithTax 73.44; {\"originalPrice\":100,\"salePrice\":75} returns discountPercent 25 and amountOff 25. Integration scenario: a deals site shows a shopper the price after a store sale and a coupon code in the order the retailer applies them, with the working under it. Pure arithmetic on the numbers sent; the order is the caller's choice because retailers differ (check the retailer's terms), nothing to update. Estimate only. Stateless: the request is processed in memory and nothing is stored. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached.",
        "tags": [
          "Everyday Math"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "originalPrice": {
                    "type": "number",
                    "minimum": 0
                  },
                  "discountPercent": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "salePrice": {
                    "type": "number",
                    "minimum": 0
                  },
                  "discounts": {
                    "description": "Several discounts, each a percentage or a fixed amount, applied one after the other in the order sent (each on the price left by the one before). Use instead of discountPercent. The price may not go below 0.",
                    "minItems": 1,
                    "maxItems": 5,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "percent",
                            "amount"
                          ],
                          "description": "percent: value is a percentage off. amount: value is a fixed amount off, in the currency of originalPrice."
                        },
                        "value": {
                          "type": "number",
                          "minimum": 0
                        }
                      },
                      "required": [
                        "type",
                        "value"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "taxPercent": {
                    "description": "With discounts: tax added on the discounted price.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  }
                },
                "required": [
                  "originalPrice"
                ],
                "additionalProperties": false
              },
              "example": {
                "originalPrice": 120,
                "discountPercent": 25
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Discount calculator client and server side from freedailypro",
                  "result": {
                    "discountAmount": 30,
                    "finalPrice": 90,
                    "savingsPercent": 25
                  }
                }
              }
            }
          },
          "400": {
            "description": "A missing originalPrice, a percentage outside 0 to 100, a negative amount, discounts sent together with discountPercent or salePrice, taxPercent without discounts, or a discount that takes the price below 0; the body says which Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/gpa": {
      "post": {
        "summary": "Calculate a GPA from course grades and credits",
        "operationId": "convertersGpa",
        "description": "Send 'courses' (each with 'grade' and 'credits') and optionally 'scale': \"4.0\" (default, grades 0 to 4) or \"percent\" (grades 0 to 100, converted with the usual bands: 90 and up is 4.0, 80 is 3.0, 70 is 2.0, 60 is 1.0, below 60 is 0). Credits must be above 0 and at most 100. Returns 'gpa' (rounded to 2 places), 'totalCredits' and 'totalPoints'. A grade outside the chosen scale (for example 5 or -1 on the 4.0 scale) or invalid credits is a 422 that names the course and the allowed range; nothing is calculated and the call is not billed. Weighted scales above 4.0 are not supported. Stateless: the request is processed in memory and nothing is stored. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached.",
        "tags": [
          "Everyday Math"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "courses": {
                    "minItems": 1,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "grade": {
                          "type": "number"
                        },
                        "credits": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "grade",
                        "credits"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "scale": {
                    "type": "string",
                    "enum": [
                      "4.0",
                      "percent"
                    ]
                  }
                },
                "required": [
                  "courses"
                ],
                "additionalProperties": false
              },
              "example": {
                "courses": [
                  {
                    "grade": 4,
                    "credits": 3
                  },
                  {
                    "grade": 3.3,
                    "credits": 4
                  },
                  {
                    "grade": 3.7,
                    "credits": 2
                  }
                ],
                "scale": "4.0"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Gpa calculator client and server side from freedailypro",
                  "result": {
                    "gpa": 3.62,
                    "totalCredits": 9,
                    "totalPoints": 32.6
                  }
                }
              }
            }
          },
          "400": {
            "description": "A missing or empty courses list, a non-numeric grade or credits, or an unknown scale; the body says which field Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    }
  }
}