{ "openapi": "3.1.1", "info": { "title": "Multi-Currency Invoice Calculator API", "version": "1.0.0", "summary": "Convert invoice lines in different currencies at ECB reference rates, with VAT, rounding and totals.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://multicurrencyinvoicecalculator.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Convert invoice lines in different currencies at ECB reference rates, with VAT, rounding and totals.", "description": "Enter invoice lines in different currencies, the invoice currency and a rate date. The calculator converts every line at the ECB euro reference rates of that date (or your own rates), applies VAT per line, shows the VAT summary and totals with either per-line or per-document rounding (and the difference between both), and writes the “converted at the ECB reference rate of …” statement. Download as CSV or an HTML table.\n\nMethodology:\n- Each line’s net amount = quantity × unit price, rounded to the minor units of its own currency, then converted with the cross rate rate(invoice currency) ÷ rate(line currency), both quoted per euro by the ECB.\n- Per-line rounding: each converted net amount and its VAT are rounded to the invoice currency’s minor units and then added up. Per-document rounding: exact converted amounts are added up per VAT rate, the net subtotal is rounded and VAT is calculated once per rate. Both totals are shown, because tax authorities and accounting systems differ in which they expect.\n- Rounding is half away from zero (commercial rounding). Lines without a currency use the invoice currency; lines without a VAT rate have 0 %.\n- ECB rates for a date are the last publication on or before it (none on weekends and TARGET holidays). Manual rates are entered per euro, exactly like the ECB quotes.\n\nNot tax advice. Check which exchange rate and rounding your tax authority requires for invoices and VAT returns.", "tags": [ "money" ], "x-mcp-tool": "multi_currency_invoice_calculator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiCurrencyInvoiceCalculatorInput" }, "examples": { "example1": { "summary": "EUR invoice with USD and GBP costs (manual ECB-style rates)", "value": { "invoiceCurrency": "EUR", "rateSource": "manual", "rateDate": "2026-10-16", "manualRates": "USD 1.1253\nGBP 0.84385", "lines": [ { "description": "Consulting (days)", "quantity": 3, "unitPrice": 850, "currency": "EUR", "vatRate": 19 }, { "description": "Cloud hosting", "quantity": 1, "unitPrice": 412.37, "currency": "USD", "vatRate": 19 }, { "description": "Conference ticket", "quantity": 2, "unitPrice": 299.99, "currency": "GBP", "vatRate": 7 }, { "description": "Travel expenses (no VAT)", "quantity": 1, "unitPrice": 123.45, "currency": "USD", "vatRate": 0 } ], "rounding": "line" } }, "example2": { "summary": "CHF invoice, document rounding (cross rates via EUR)", "value": { "invoiceCurrency": "CHF", "rateSource": "manual", "manualRates": "CHF 0.9272\nUSD 1.1253\nJPY 177.82", "rounding": "document", "lines": [ { "description": "Licences", "quantity": 7, "unitPrice": 19.99, "currency": "USD", "vatRate": 8.1 }, { "description": "Support", "quantity": 1, "unitPrice": 15000, "currency": "JPY", "vatRate": 8.1 }, { "description": "Setup", "quantity": 1, "unitPrice": 250, "currency": "CHF", "vatRate": 8.1 } ] } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiCurrencyInvoiceCalculatorResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "MultiCurrencyInvoiceCalculatorInput": { "type": "object", "additionalProperties": false, "properties": { "invoiceCurrency": { "title": "Invoice currency", "type": "string", "maxLength": 3, "default": "EUR" }, "rateSource": { "title": "Exchange rates", "type": "string", "enum": [ "ecb", "manual" ], "default": "ecb" }, "rateDate": { "title": "Rate date", "description": "E.g. the invoice or supply date. Empty: latest ECB rates. Weekends/holidays use the last publication before.", "type": "string", "format": "date" }, "manualRates": { "title": "Manual rates", "description": "One per line, as units per 1 EUR (ECB convention). Used with \"Enter rates manually\".", "type": "string", "maxLength": 4000 }, "lines": { "title": "Invoice lines", "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "additionalProperties": false, "properties": { "description": { "title": "Description", "type": "string", "maxLength": 200 }, "quantity": { "title": "Quantity", "type": "number", "minimum": -1000000000, "maximum": 1000000000, "default": 1 }, "unitPrice": { "title": "Unit price", "type": "number", "minimum": -1000000000000, "maximum": 1000000000000 }, "currency": { "title": "Currency", "type": "string", "maxLength": 3 }, "vatRate": { "title": "VAT %", "type": "number", "minimum": 0, "maximum": 100, "default": 0 } }, "required": [ "unitPrice" ] } }, "rounding": { "title": "Rounding", "type": "string", "enum": [ "line", "document" ], "default": "line" } }, "required": [ "invoiceCurrency", "lines" ] }, "MultiCurrencyInvoiceCalculatorResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "invoiceCurrency", "rounding", "rates", "ratesUsed", "lines", "vatSummary", "totals", "alternativeRounding", "roundingDifference", "statement" ], "properties": { "invoiceCurrency": { "type": "string" }, "rounding": { "type": "string" }, "rates": { "type": "object", "additionalProperties": false, "required": [ "date", "source", "url", "fetchedAt", "stale" ], "properties": { "date": { "type": "string", "description": "Reference date of the rates." }, "requestedDate": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "ecb-daily", "ecb-sdmx", "manual" ] }, "url": { "type": [ "string", "null" ] }, "fetchedAt": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" } } }, "ratesUsed": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "currency", "perEur", "toInvoice" ], "properties": { "currency": { "type": "string" }, "perEur": { "type": "number" }, "toInvoice": { "type": "number", "description": "Invoice-currency units per 1 unit of this currency." } } } }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "description", "quantity", "unitPrice", "currency", "netOriginal", "rate", "net", "vatRate", "vat", "gross" ], "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "currency": { "type": "string" }, "netOriginal": { "type": "number" }, "rate": { "type": "number" }, "net": { "type": "number" }, "vatRate": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" } } } }, "vatSummary": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "vatRate", "net", "vat", "gross" ], "properties": { "vatRate": { "type": "number" }, "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" } } } }, "totals": { "type": "object", "additionalProperties": false, "required": [ "net", "vat", "gross" ], "properties": { "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" } } }, "alternativeRounding": { "type": "object", "additionalProperties": false, "required": [ "method", "net", "vat", "gross" ], "properties": { "method": { "type": "string" }, "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" } } }, "roundingDifference": { "type": "number", "description": "Gross total of this method minus the other method." }, "statement": { "type": "string" } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }