{
  "openapi": "3.0.3",
  "info": {
    "title": "Currency and VAT API",
    "version": "1.5.1",
    "description": "Daily reference exchange rates for about 200 currencies, crypto and metals with the as-of date, EU VAT number validation, plus VAT, GST and sales tax rates and calculations. Convert amounts between about 200 currencies, crypto assets and metals using daily reference rates (the as-of date and source are in every response, a standard set is the fallback and supplies history ranges for about 30 currencies; the response says plainly that rates are daily reference values, not live market rates), validate EU VAT numbers (layout check per member state plus a live VIES lookup), look up standard and reduced VAT and GST rates for 59 countries and regions with a data version and a verification note per country, add or extract VAT or GST on an amount, and calculate US sales tax from a state base-rate table. Tax rates come from one table file per country, are updated each tax year and carry their source. Estimates for information, not tax advice. 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": "Currency & VAT",
      "description": "Daily reference exchange rates for about 200 currencies, crypto and metals with the as-of date, EU VAT number validation, plus VAT, GST and sales tax rates and calculations."
    }
  ],
  "paths": {
    "/v1/converters/sales-tax": {
      "post": {
        "summary": "Calculate sales tax on an amount, adding or extracting tax, with US state base-rate lookup",
        "operationId": "convertersSalesTax",
        "description": "Adds sales tax to an amount ('mode' add, the default) or extracts it from a tax-inclusive amount (extract). Send 'taxPercent' to use your own rate, or 'state' (two-letter code such as TX, or the full name; 50 states and DC) to use that state's BASE sales tax rate. Only the state base rate is applied: city, county and special-district sales taxes are NOT included, because the right local rate depends on the exact address. The response also returns the state's average combined (state plus local) rate for reference, clearly labelled and never applied; for an exact local rate send taxPercent. 'taxPercent' wins if both are sent. Where the data comes from: Tax Foundation state sales tax tables (1 July 2026), a secondary source, so dataStatus is 'estimate'. Update process: one table file shared with the FreeDailyPro website, reviewed by FreeDailyPro each January and July. Exemptions (groceries, clothing, services) are not modelled. Estimate, not tax advice. Rate vintage: the response includes 'ratesAsOfDate' (the table's own date, 2026-07-01), 'ratesCheckedOn' (2026-10-30, when all 51 rows were compared with the Tax Foundation midyear 2026 table), 'ratesAgeDays', 'ratesStale' (true once the table is more than 200 days old, with a warning added to notes) and 'steps' (the working). Who calls it: checkout and quoting tools, invoicing and expense apps, shopping assistants and chatbots or MCP agents. Worked example: {\"amount\":100,\"state\":\"Louisiana\"} applies the 5% state base rate (tax 5, total 105) and returns averageCombinedRatePct 10.13 for reference; send taxPercent 10.13 to use the average combined rate instead. More options: 'zip' (a US ZIP code) finds the state; the rate is filled in only where it is exact: 0% for Delaware, New Hampshire and Oregon, or the state rate where the Tax Foundation midyear 2026 table shows no local add-on. For any other state a ZIP can cross city, county and district lines, so no rate is guessed: the call returns 400 with a message saying so unless you also send taxPercent or state (the response's 'zip' object then carries the message, source and the state's official lookup page where one was verified). 'items' (several items with price, qty and taxable true or false, plus shipping, shippingTaxable and discountPct) returns a 'cart' with taxable and exempt subtotals, tax, total, steps and lines; amount is then not needed. Items work with mode add only. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Currency & VAT"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount": {
                    "description": "Amount to tax (or the tax-inclusive amount in extract mode). Required unless items is sent.",
                    "type": "number",
                    "minimum": 0
                  },
                  "zip": {
                    "description": "US ZIP code (5 digits or ZIP+4). Used to find the STATE. The rate is filled in only where it is exact: 0% for DE, NH and OR, or the state rate for states with no local add-on in the Tax Foundation midyear 2026 table. For any other state no rate is guessed (a ZIP can cross city, county and district lines): the response's zip.message says so, and you send taxPercent or state. Response adds 'zip' with the state, status, message, source and the state's official lookup page where one was verified.",
                    "type": "string"
                  },
                  "items": {
                    "description": "Several items (mode add only). Response adds 'cart' with taxable and exempt subtotals, tax, total, steps and lines.",
                    "minItems": 1,
                    "maxItems": 100,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "number",
                          "minimum": 0
                        },
                        "qty": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 9007199254740991
                        },
                        "taxable": {
                          "description": "Default true. false marks the item exempt.",
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "price"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "shipping": {
                    "description": "With items: shipping charged.",
                    "type": "number",
                    "minimum": 0
                  },
                  "shippingTaxable": {
                    "description": "With items: true adds shipping to the taxable amount. Default false (rules differ by state, so you choose).",
                    "type": "boolean"
                  },
                  "discountPct": {
                    "description": "With items: percentage discount on every line.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "taxPercent": {
                    "description": "Tax rate in percent. Required unless state or an exact zip is sent. Takes priority over state.",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "state": {
                    "description": "US state (two-letter code such as TX, or the full name; DC included). Looks up the STATE base sales tax rate only (Tax Foundation, 1 July 2026). Local city, county and district rates are not included.",
                    "type": "string"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "add",
                      "extract"
                    ]
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "amount": 100,
                "state": "TX"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "result": {
                    "taxAmount": 6.25,
                    "total": 106.25,
                    "net": 100,
                    "ratePct": 6.25,
                    "rateSource": "US state base rate (local taxes excluded)",
                    "state": "Texas",
                    "stateBaseRatePct": 6.25,
                    "averageCombinedRatePct": 8.2,
                    "ratesAsOf": "Tax Foundation, 1 July 2026",
                    "taxYear": 2026,
                    "sources": "Tax Foundation sales tax tables (1 July 2026). Tax year 2026. FreeDailyPro table last checked 2026-10-11 (compiled from secondary sources, confirm with the authority). Next review: January and July. https://taxfoundation.org/data/all/state/sales-tax-rates/",
                    "dataStatus": "estimate",
                    "notes": [
                      "Rate used: Texas STATE base rate 6.25%. Local (city, county, district) sales taxes are not included; the average combined rate is 8.2% (reference only, not applied). For an exact local rate send taxPercent.",
                      "Some goods (groceries, clothing, services) are taxed at other rates or exempt, which is not modelled.",
                      "Texas is among the states carried from earlier Tax Foundation tables; the 1 July 2026 figure was not separately confirmed. Marked as an estimate."
                    ],
                    "disclaimer": "Estimate for information only. Not tax, legal or financial advice; check the figures with the tax authority or a qualified adviser."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Neither taxPercent nor state (nor an exact zip), a ZIP that is not 5 digits or has no single rate, a taxPercent outside 0 to 100, no amount and no items, or an unknown state 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/vat-gst": {
      "post": {
        "summary": "Calculate VAT or GST on an amount using a 59-entry country and province rate table",
        "operationId": "convertersVatGst",
        "description": "Adds VAT/GST to a net amount, or extracts it from a gross amount ('amountIncludesTax': true). Send 'ratePct' for any rate, or 'country' to use that country's STANDARD rate from a built-in table: the 27 EU member states, the UK, Norway, Switzerland, Iceland, Turkey, Ukraine, Canada (GST, HST, PST combined by province group), Australia, New Zealand, Singapore, India (GST; 'India' works), Japan, South Korea, Thailand, Philippines, Indonesia, UAE, Saudi Arabia, Israel, South Africa, Kenya, Nigeria, Egypt, Mexico, Chile, Colombia and Argentina. Names are case-insensitive and 'UK' works; an ambiguous or unknown name returns a 400 that lists the valid entries. The response includes the standard rate, the country's common reduced rates (send one as ratePct to use it), ratesAsOf, taxYear and sources. 'ratePct' wins if both are sent. Where the data comes from: the standard rates of the 27 EU states were compared with a published 2026 EU rate table on 30 Oct 2026; reduced rates and non-EU rates were compiled from the national tax authorities and have not all been re-verified, so dataStatus is 'estimate'. Update process: one table file shared with the FreeDailyPro website, reviewed by FreeDailyPro each January. It is not for US sales tax (use /v1/converters/sales-tax). Estimate, not tax advice. Start from a VAT amount or total an invoice: send 'vatAmount' (the VAT printed on a receipt) with ratePct or country to get net and gross (netRange gives the net amounts that would print that VAT after rounding to the cent; a rate of 0 is refused), or 'lines' (up to 200 { amount, ratePct } objects; a line without ratePct uses the top-level ratePct or the country's standard rate) to get 'byRate' subtotals, a grand total and, for Canada - Quebec, the GST and QST split. With lines, 'amountIncludesTax' says whether the amounts are gross. Tax is worked out once per rate on that rate's subtotal and rounded to the cent. Send only one of amount, vatAmount and lines. Every mode returns 'steps'. Who calls it: accounting and bookkeeping software, expense-claim and receipt-scanning tools, invoicing apps for UK and EU sole traders, and chatbots or MCP agents. Worked examples: {\"vatAmount\":20,\"ratePct\":20} returns net 100, gross 120; {\"lines\":[{\"amount\":100,\"ratePct\":20},{\"amount\":50,\"ratePct\":5}]} returns tax 22.5 and gross 172.5. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Currency & VAT"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount": {
                    "description": "The amount, in any currency. Send this, or vatAmount, or lines.",
                    "type": "number"
                  },
                  "vatAmount": {
                    "description": "The VAT amount shown on a receipt: returns the net and gross it implies at the rate (needs a rate above 0). Use instead of amount.",
                    "type": "number",
                    "minimum": 0
                  },
                  "lines": {
                    "description": "Invoice lines at different rates: returns a subtotal per rate (byRate) and a grand total. Use instead of amount.",
                    "maxItems": 200,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "amount": {
                          "type": "number",
                          "minimum": 0,
                          "description": "The line amount (net, or gross when amountIncludesTax is true)."
                        },
                        "ratePct": {
                          "description": "This line's rate in percent. Defaults to the top-level ratePct or the country's standard rate.",
                          "type": "number",
                          "minimum": 0
                        }
                      },
                      "required": [
                        "amount"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "ratePct": {
                    "description": "VAT/GST rate in percent. Required unless country is sent. Takes priority over country.",
                    "type": "number"
                  },
                  "country": {
                    "description": "Country name (for example Germany, United Kingdom, Australia, Singapore, UAE). Looks up the standard VAT/GST rate. Canada has one entry per province group, e.g. 'Canada - Ontario HST'. The error for an unknown name lists every supported entry.",
                    "type": "string"
                  },
                  "amountIncludesTax": {
                    "description": "true when amount already includes the tax (the tax is taken out of it).",
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "amount": 120,
                "country": "Germany",
                "amountIncludesTax": false
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "result": {
                    "net": 120,
                    "tax": 22.8,
                    "gross": 142.8,
                    "ratePct": 19,
                    "country": "Germany",
                    "standardRatePct": 19,
                    "reducedRatesPct": [
                      7
                    ],
                    "rateSource": "country standard rate",
                    "ratesAsOf": "October 2026",
                    "taxYear": 2026,
                    "sources": "Each country's tax authority. Tax year 2026. FreeDailyPro table last checked 2026-10-11 (compiled from secondary sources, confirm with the authority). Next review: January.",
                    "dataStatus": "estimate",
                    "notes": [
                      "Rate used: Germany standard rate 19%. Reduced rates also exist (7%) for some goods and services; send one as ratePct to use it.",
                      "Standard rates for the 27 EU member states were compared with a published 2026 table on 30 Oct 2026. Reduced rates and non-EU countries were compiled from memory of the national authorities and are not re-verified; confirm with the tax authority."
                    ],
                    "disclaimer": "Estimate for information only. Not tax, legal or financial advice; check the figures with the tax authority or a qualified adviser."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Body: {error, code, details: {fieldErrors, formErrors, issues, examples}}. code is invalid_input (wrong type, unknown field), missing_fields (none of amount, vatAmount and lines), conflicting_fields (more than one of them), missing_rate (no ratePct or country, vatAmount with a rate of 0, a line without any rate), invalid_amount, invalid_rate, invalid_lines, invalid_combination (amountIncludesTax with vatAmount) or unknown_country (unknown name or one that matches several entries; the message lists the supported names). details.examples shows the four accepted forms: net amount with country, gross amount with ratePct, vatAmount with ratePct, and lines 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/exchange-rates": {
      "post": {
        "summary": "Exchange rates: daily reference rates for about 200 currencies, crypto and metals, with a standard-set fallback, the as-of date and the source shown",
        "operationId": "convertersExchangeRates",
        "description": "Send 'amount' (default 1), 'from' (default USD) and 'to' (one code or a list of up to 20; required), optionally 'date' for a past day (YYYY-MM-DD, see Valid dates and errors below; a weekend or holiday returns the latest earlier working day with a 'dateNote'), or 'listCurrencies' true. Returns 'rates', 'converted', the rate 'date', 'source', 'sourceId' and a 'note'. Two sources: the broad set (sourceId reference-broad: daily rates for about 200 codes, namely ISO currencies plus common crypto assets and the metals XAU, XAG, XPT and XPD; tried first) and the standard set (sourceId reference-daily, about 30 currencies; the fallback). The optional 'source' picks one: auto (default: broad first, the standard set if the broad set cannot be fetched, with a providerNote saying so), broad (broad only, 502 if unavailable) or standard (standard set only). A history range ('startDate' with 'endDate', up to 366 days and 5 currencies) comes from the standard set only, so it needs standard-set currencies. 'listCurrencies' returns the codes with type (fiat, metal or other), a name where known, per-type counts and the date of the set. Limits: these are daily reference rates, refreshed about once a day, not live and not intraday; the response says 'live: false' and 'stale: true' with a warning when the newest data is more than 5 days old. They can differ from what a bank, card network or exchange charges, crypto and metal values are not tradable prices, and the broad set is a compiled daily set without a per-currency source list, so use them as reference only. Converted amounts are rounded to 2 decimals, or to 6 decimals when the result is under 0.01 so a small amount never shows as 0 (8 decimals for crypto and 'other' codes); 'amount' must be from 0.000001 to 1e12 (1,000,000,000,000), anything else is a 400. Valid dates and errors: Standard-set fiat currencies (about 30, for example USD, EUR, GBP, JPY, INR) have dated rates from 1999-01-04 up to today. Crypto (for example BTC), metals (XAU, XAG, XPT, XPD) and every other currency outside the standard list have dated rates from 2024-03-02 only. A dated request before 2024-03-02 for such a code, or with source broad, is answered with 400 before any provider is called, and the message names both start dates; standard-set currencies before 2024-03-02 are answered from the standard set with a providerNote. A date before 1999-01-04 or in the future is a 400. A 502 (with code rate_provider_unavailable) means only that the chosen provider could not be reached right now. Fallback: when neither provider can be reached, a latest-rates request (no date) is answered from a fixed built-in snapshot dated 2026-11-17 (publicly available reference rates of that day), refreshed monthly by hand and not updated at run time; that answer has source \"Built-in backup rates (dated 2026-11-17)\", sourceId built-in-snapshot, stale true, fallback true and a warning, so it cannot be mistaken for current data. A dated or range request is never answered from the snapshot. If neither source can be reached, a latest-rates request falls back to a labelled old built-in snapshot and a dated or range request returns 502 rather than made-up rates. Who calls it: invoicing and e-commerce tools, expense apps, dashboards, chatbots and MCP agents. Worked example: {\"amount\":100,\"from\":\"USD\",\"to\":[\"EUR\",\"BTC\"]} against a set dated 2026-10-31 with 1 USD = 0.86 EUR returns 86 EUR. Data: the rates are compiled once a day from publicly available sources into one consolidated set (market data only; nothing you send is stored), and every request reads the newest stored day. If no stored day can be read, a latest-rates request falls back to a labelled old built-in snapshot (sourceId built-in-snapshot, stale true, fallback true); backup rates are refreshed monthly. Source attributions are kept in the internal documentation, not in responses. Rates data notice: exchange rates are compiled from multiple publicly available sources. They are not live data. They are previous-day data, typically from the most recent business day (shown by the date or ratesAsOf field of the response), provided for your information only and to be used as reference. They are indicative, not live trading rates, and not the rate a bank or card will give you. FreeDailyPro does not provide trading guidance, investment advice or trading services. If a rights holder or data provider tells FreeDailyPro about restrictions on the use of any data, we will review the notice promptly and comply for future use. FreeDailyPro accepts no responsibility for how users apply this information, except where the public source page itself states that the data is restricted for use. To send a notice, use the Contact page: https://freedailypro.com/contact. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Currency & VAT"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount": {
                    "description": "Amount to convert (default 1), from 0.000001 to 1e12 (1,000,000,000,000); outside that range is a 400. Converted fiat values keep 2 decimals, or 6 when the result is under 0.01, so a small amount never rounds to 0; crypto and other codes keep 8.",
                    "type": "number",
                    "minimum": 0.000001,
                    "maximum": 1000000000000
                  },
                  "from": {
                    "description": "Currency code to convert from (default USD): ISO codes such as USD, plus crypto and metal codes in the broad set.",
                    "type": "string"
                  },
                  "to": {
                    "description": "Currency code, or a list of up to 20 codes, to convert to. Required unless listCurrencies is true.",
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    ]
                  },
                  "date": {
                    "description": "A past date, YYYY-MM-DD, up to today: the daily rate for that day. Standard-set fiat currencies go back to 1999-01-04; crypto, metals and the other broad-set currencies only from 2024-03-02, so a date before 2024-03-02 with BTC, XAU or any code outside the standard set, or with source broad, is a 400 that names both start dates. A future date or one before 1999-01-04 is a 400. On a weekend or holiday you get the latest earlier working day, with a dateNote. Example: 2024-03-15.",
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  },
                  "startDate": {
                    "description": "History: first day of a range of up to 366 days (send with endDate). Must be between 1999-01-04 and today. Example: 2024-01-02.",
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  },
                  "endDate": {
                    "description": "History: last day of the range, on or before today. Example: 2024-03-15.",
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  },
                  "listCurrencies": {
                    "description": "true returns the supported currency codes (with type and name) and the date of the latest rates.",
                    "type": "boolean"
                  },
                  "source": {
                    "description": "auto (default): the broad daily set of about 200 currencies, crypto and metals, falling back to the standard set; broad: only the broad set; standard: only the standard set (about 30 currencies, and the only one with history ranges).",
                    "type": "string",
                    "enum": [
                      "auto",
                      "broad",
                      "standard"
                    ]
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "from": "USD",
                "to": "EUR"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "result": {
                    "source": "Publicly available reference rates",
                    "sourceId": "reference-broad",
                    "note": "Previous-day reference rates, not live data: compiled from publicly available sources, they usually reflect the most recent business day (the date is in ratesAsOf or date) and are provided for information only, to be used as reference. They are not live trading rates and not the rate a bank or card will give you. FreeDailyPro does not provide trading guidance, investment advice or trading services. Crypto and metal values are daily reference values, not tradable prices.",
                    "live": false,
                    "from": "USD",
                    "amount": 100,
                    "date": "2026-10-31",
                    "stale": false,
                    "rates": {
                      "EUR": 0.86,
                      "GBP": 0.75
                    },
                    "converted": {
                      "EUR": 86,
                      "GBP": 75
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A malformed currency code or date, a date in the future or before 1999-01-04, a dated request before 2024-03-02 for crypto, metals, another currency outside the standard set or source broad (the message names both start dates), an amount below 0.000001 or above 1e12, a missing 'to', more than 20 currencies (5 for a history), a range over 366 days, a startDate after endDate, source broad with a date range, or a code with no rate in the chosen set; 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."
          },
          "502": {
            "description": "The chosen rate source could not be reached right now (source broad, a past date or a date range). The body is {error, code: rate_provider_unavailable}; a latest request in auto mode falls back to a labelled built-in snapshot instead Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/vat-validate": {
      "post": {
        "summary": "Validate an EU VAT number: layout check per member state plus a live VIES lookup",
        "operationId": "convertersVatValidate",
        "description": "Send 'vatNumber' (for example DE123456789, spaces and dots allowed) and optionally 'country' when the number has no prefix, and 'offlineOnly' true to skip the live lookup. Step 1 is an offline layout check against the national format of each EU member state (plus XI for Northern Ireland goods; Greece is EL, GR is accepted). A number that fails it returns valid false, checked 'format' and a reason, and is never sent to VIES. Step 2 asks the European Commission's VIES service whether the number is registered for intra-EU trade: the answer is valid true or false, checked 'vies', with the registered name and address when the member state shares them and the request date. Limits: a good layout does not prove registration (only VIES does), the UK (GB) is no longer in VIES, and VIES is often down for single member states. When VIES does not answer the endpoint returns 503 with a plain message, which is not billed, instead of guessing; results are cached in memory for 10 minutes and nothing is stored. VIES confirms a number exists, not that a business is trustworthy. The live call could not be made from the build environment, so the tests use a mocked provider and one real lookup must be checked after deploy. 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": [
          "Currency & VAT"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "vatNumber": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 40,
                    "description": "The EU VAT number, with or without the two-letter prefix and with spaces or dots, for example DE123456789 or 'DE 123.456.789'."
                  },
                  "country": {
                    "description": "Two-letter country code when vatNumber has no prefix (Greece is EL).",
                    "type": "string"
                  },
                  "offlineOnly": {
                    "description": "true checks only the number layout and skips the live VIES lookup.",
                    "type": "boolean"
                  }
                },
                "required": [
                  "vatNumber"
                ],
                "additionalProperties": false
              },
              "example": {
                "vatNumber": "DE123456789"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "result": {
                    "vatNumber": "DE123456789",
                    "country": "DE",
                    "countryName": "Germany",
                    "formatValid": true,
                    "valid": true,
                    "checked": "vies",
                    "name": "EXAMPLE GMBH",
                    "address": "MUSTERSTRASSE 1, 10115 BERLIN",
                    "requestDate": "2026-11-01",
                    "note": "valid true means the number is registered for intra-EU trade in VIES at the request date. Some member states return no name or address."
                  }
                }
              }
            }
          },
          "400": {
            "description": "vatNumber is missing, has no country prefix and no country was sent, or country is not two letters; 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."
          },
          "503": {
            "description": "VIES did not answer, so nothing was checked; try again later Not billed: a failed call does not count against your plan's calls.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying"
              }
            }
          }
        }
      }
    },
    "/v1/converters/vat-rates": {
      "post": {
        "summary": "VAT and GST rates: standard and reduced rates for 61 countries and Canadian province groups with a data version, as-of date and verification note per country",
        "operationId": "convertersVatRates",
        "description": "Send nothing for the whole table, or 'country' (name or ISO code), 'region' (eu, other-europe, canada, asia-pacific, middle-east-africa, americas) or 'currency' to filter. Returns 'rates' (country, region, standardRatePct, reducedRatesPct, currency, and a 'verification' note saying how that row was checked), plus 'dataVersion', 'asOf', 'taxYear', 'tableLastEntered', 'euStandardRatesComparedOn', 'count', 'sources', 'dataStatus' ('estimate'), 'nextReview' and 'notes'. Standard and common reduced rates only: zero rates, exemptions, thresholds, special schemes and regional rates (apart from the Canadian provinces) are not included. Who calls it: invoicing and e-commerce checkouts, accounting tools, marketplace sellers, cross-border pricing, chatbots and MCP agents. Worked example: an empty body returns 59 rows, dataVersion 2026-10; {\"country\":\"Austria\"} returns standard 20% with the reduced rates. EU standard rates were compared with a published 2026 table on 30 Oct 2026; reduced rates and non-EU rows were compiled from national sources by FreeDailyPro and not all re-verified, so each row says so; confirm with the tax authority before invoicing. Update process: one table file shared with the website, reviewed each January. Use the VAT/GST calculator endpoint (/v1/converters/vat-gst) to apply a rate to an amount. Pure arithmetic from the request: no customer data is stored. 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": [
          "Currency & VAT"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "country": {
                    "description": "A country name, or a list of names (for example Germany, UK, Canada - Ontario HST). Leave out for the whole table.",
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    ]
                  },
                  "region": {
                    "description": "Only the countries of one region.",
                    "type": "string",
                    "enum": [
                      "eu",
                      "other-europe",
                      "canada",
                      "asia-pacific",
                      "middle-east-africa",
                      "americas"
                    ]
                  },
                  "currency": {
                    "description": "Only the countries that use this currency code, for example EUR.",
                    "type": "string"
                  }
                },
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "result": {
                    "dataVersion": "2026-10",
                    "asOf": "October 2026",
                    "taxYear": 2026,
                    "tableLastEntered": "2026-10-11",
                    "euStandardRatesComparedOn": "2026-10-30",
                    "count": 59,
                    "rates": [
                      {
                        "country": "Austria",
                        "region": "eu",
                        "standardRatePct": 20,
                        "reducedRatesPct": [
                          13
                        ],
                        "currency": "EUR",
                        "verification": "standard rate compared with a published 2026 table on 30 Oct 2026; reduced rates compiled from memory of national sources"
                      }
                    ],
                    "sources": "Each country's tax authority. Tax year 2026. FreeDailyPro table last checked 2026-10-11 (compiled from secondary sources, confirm with the authority). Next review: January.",
                    "dataStatus": "estimate",
                    "nextReview": "January",
                    "notes": [
                      "Standard and common reduced rates only. Zero rates, exemptions, thresholds, special schemes and regional rates (apart from the Canadian provinces listed) are not included."
                    ],
                    "disclaimer": "Estimate for information only. Not tax, legal or financial advice; check the figures with the tax authority or a qualified adviser."
                  }
                }
              }
            }
          },
          "400": {
            "description": "An unknown region (the body lists the valid ones) 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."
          }
        }
      }
    }
  }
}