Validate Invoice Totals

finance.validate_invoice_totals

ProductionBounded custom (Class B)Deterministicstrictmoderatev1.0.0

No network

Overview

You pass invoice line primitives and stated totals; we recompute net, tax, and gross figures and report every discrepancy with magnitude and tolerance. We use the same decimal VAT arithmetic as finance.calculate_vat. We do not judge whether tax rates are legally correct or validate VAT numbers. Do not use this for tax compliance or rate selection.

Stated totals arrive already rounded by someone else's system, so a cent of drift can hide until a payment fails. We rebuild every figure from quantity, price, discount and rate, then show you the signed difference on each one.

Reliability

Same invoice, same verdict — exact decimal arithmetic throughout, and we never change your document. An invoice that does not add up comes back as a normal success with valid:false, discrepancies and findings, so reserve your error path for the codes below. Every stated figure you omit is skipped rather than assumed. INVOICE_STRUCTURE_INVALID — trigger: the invoice object is empty, its lines key is missing or is not an array, or one of the entries in lines is not an object; retryable: no, the same payload always fails; next: send invoice.lines as an array of objects, using an empty array if the invoice genuinely has no lines. CURRENCY_UNKNOWN — trigger: invoice.currency is missing, blank, or outside the twenty currencies we support; retryable: no; next: set a supported ISO 4217 code on the invoice — it also decides the scale and the default tolerance. INVOICE_LINE_LIMIT_EXCEEDED — trigger: invoice.lines holds more than 1,000 entries; retryable: no; next: check the invoice in batches of 1,000 lines or fewer, dropping the header totals from every batch but the one you reconcile against. AMOUNT_INVALID — trigger: any line or header amount we cannot read as a plain decimal, a line discount larger than the line itself, an unknown rounding mode, or a tolerance that is not a decimal; retryable: no; next: read the line id in the message, send that figure as a plain decimal string, and keep discounts at or below quantity times unitPrice.

Context footprint

Returns computed vs stated totals with signed differences so you can fix or reject. A successful call costs 1 execution credit.

When to use it

When you have both the line primitives and the header totals, and you need to know whether they agree before you pay, post or export the invoice.

When you need to pick the correct tax rate, or to check a VAT registration number or any other business identity.

Scope

Note

Arithmetic consistency check for invoice lines and header totals.

Non-goals

Does not validate VAT registration numbers
Does not judge whether tax rates are legally correct
Does not modify or correct the invoice

Properties

IdempotentRetry safeStreaming supportedFile input supportedRequires external service

Capabilities

mathvalidation

Cost & billing

Flat rate per invocation

MetercallsBillable onsuccessCost per call1 credit

File handling

Accepts file_refProduces file_refMax input256 KB

How we handle your data

Sensitive input, safe output

What this means

This skill may receive sensitive content, but it does not target sensitive data and returns only a structured non-sensitive result.

Squillify guarantees

Runs inside Squillify
This skill runs inside Squillify.
Payloads are not sent to an external service by this skill.
Squillify does not permanently store submitted payloads.
Telemetry records metadata only, not submitted content.
Submitted payloads are not used for training.
Submitted payloads are not reviewed by humans.
This skill does not target sensitive data.
The response does not contain submitted content.

Your responsibility

Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.

Read the Microskill Data Handling Policy

Input schema

Field	Type	Required	Description
invoice	object	Yes	Closed invoice with a required currency, up to 1,000 lines, and optional header totals compared only when present.
options	object	No	Optional check settings for accepted drift, rounding mode, and whether the rounding point is echoed as per_line or total_only; omit it for HALF_UP with a one-minor-unit tolerance.

Output schema

Field	Type	Required	Description
valid	boolean	Yes	True when every figure you stated is within tolerance; false is a successful answer that the invoice does not add up.
currency	string	Yes	ISO 4217 code from the invoice, upper-cased in the receipt.
computed	object	Yes	Closed header money figures as decimal strings at the currency scale: subtotalNet, totalDiscount, totalTax, totalGross, and amountDue.
stated	object	Yes	Header figures you actually sent, re-rendered at the currency scale; keys are only the subset present, so an invoice with no header totals is empty.
discrepancies	array	Yes	Every header and line figure that differs; empty when the invoice is clean.
lineResults	array	Yes	One object per line in input order with id, valid, and that line's own discrepancies.
byTaxRate	array	Yes	Lines rolled up per distinct taxRatePercent with ratePercent, net, and tax, sorted by rate text.
findings	array	Yes	Readable trail of mismatches, tolerated drift, and omitted stated fields, capped at 2,000 entries.
roundingApplied	object	Yes	Closed rounding receipt naming the mode, currency-scale, and per_line or total_only point used to recompute.
_meta	object	No	Audit trail with how many lines the invoice carried and the decimal tolerance actually applied.

API contract

POST /v1/execute

curl

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"finance.validate_invoice_totals","input":{"invoice":{"currency":"EUR","lines":[{"id":"1","quantity":"2","unitPrice":"50.00","discountPercent":"10","taxRatePercent":"21","lineNet":"90.00","lineTax":"18.90","lineTotal":"108.90"}],"subtotalNet":"90.00","totalDiscount":"10.00","totalTax":"18.90","totalGross":"108.90","amountPaid":"0.00","amountDue":"108.90"},"options":{"tolerance":"0.01"}}}'

Integrations

TypeScript SDK

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("finance.validate_invoice_totals", {"options":{"rounding":"HALF_UP","tolerance":"0.01"},"invoice":{"currency":"EUR","lines":[{"id":"1","quantity":"2","unitPrice":"50.00","discountPercent":"10","taxRatePercent":"21","lineNet":"90.00","lineTax":"18.90","lineTotal":"108.90"}],"subtotalNet":"90.00","totalDiscount":"10.00","totalTax":"18.90","totalGross":"108.90","amountPaid":"0.00","amountDue":"108.90"}});

Errors

Code	HTTP	Retryable	Description
VALIDATION_ERROR	400	No	The request payload failed schema validation.
UNAUTHORIZED	401	No	Missing or invalid API key.
SKILL_NOT_ACCESSIBLE	403	No	The API key is not granted access to this skill.
SKILL_NOT_AVAILABLE_FOR_PLAN	403	No	This skill is not included in your current plan.
PLAN_ELIGIBILITY_UNAVAILABLE	503	Yes	Plan eligibility could not be decided. Retry after backoff.
SKILL_NOT_FOUND	404	No	The requested skill or version does not exist.
TENANT_RATE_LIMITED	429	Yes	Request rate limit exceeded. Retry after backoff.
QUOTA_EXCEEDED	429	Yes	Plan quota exhausted. Retryable once the quota period resets.
EXECUTION_TIMEOUT	504	Yes	Execution exceeded the allowed time budget.
INVOICE_STRUCTURE_INVALID	400	No	The request payload failed this skill's input validation.
CURRENCY_UNKNOWN	400	No	The request payload failed this skill's input validation.
INVOICE_LINE_LIMIT_EXCEEDED	429	No	A size, quota, rate, or time limit was exceeded.
AMOUNT_INVALID	400	No	The request payload failed this skill's input validation.

Other limits

Limit	Value
Recommended inline bytes	32 KiB

Limitations

Does not validate VAT registration numbers
Does not judge whether tax rates are legally correct
Does not modify or correct the invoice
Legal tax compliance decisions
VAT number or business identity validation
Choosing the correct tax rate

How to call

POST /v1/execute (requires authentication)

Request bodyjson

{
  "skillKey": "finance.validate_invoice_totals",
  "input": {
    "options": {
      "rounding": "HALF_UP",
      "tolerance": "0.01"
    },
    "invoice": {
      "currency": "EUR",
      "lines": [
        {
          "id": "1",
          "quantity": "2",
          "unitPrice": "50.00",
          "discountPercent": "10",
          "taxRatePercent": "21",
          "lineNet": "90.00",
          "lineTax": "18.90",
          "lineTotal": "108.90"
        }
      ],
      "subtotalNet": "90.00",
      "totalDiscount": "10.00",
      "totalTax": "18.90",
      "totalGross": "108.90",
      "amountPaid": "0.00",
      "amountDue": "108.90"
    }
  }
}

Examples

Consistent single-line EUR invoice passes

Inputjson

{
  "options": {
    "rounding": "HALF_UP",
    "tolerance": "0.01"
  },
  "invoice": {
    "currency": "EUR",
    "lines": [
      {
        "id": "1",
        "quantity": "2",
        "unitPrice": "50.00",
        "discountPercent": "10",
        "taxRatePercent": "21",
        "lineNet": "90.00",
        "lineTax": "18.90",
        "lineTotal": "108.90"
      }
    ],
    "subtotalNet": "90.00",
    "totalDiscount": "10.00",
    "totalTax": "18.90",
    "totalGross": "108.90",
    "amountPaid": "0.00",
    "amountDue": "108.90"
  }
}

Expected outputjson

{
  "lineResults": [
    {
      "valid": true,
      "id": "1",
      "discrepancies": []
    }
  ],
  "byTaxRate": [
    {
      "net": "90.00",
      "tax": "18.90",
      "ratePercent": "21"
    }
  ],
  "findings": [],
  "computed": {
    "totalDiscount": "10.00",
    "subtotalNet": "90.00",
    "totalTax": "18.90",
    "totalGross": "108.90",
    "amountDue": "108.90"
  },
  "stated": {
    "totalDiscount": "10.00",
    "subtotalNet": "90.00",
    "totalTax": "18.90",
    "totalGross": "108.90",
    "amountDue": "108.90"
  },
  "currency": "EUR",
  "discrepancies": [],
  "roundingApplied": {
    "scale": 2,
    "mode": "HALF_UP",
    "point": "per_line"
  },
  "valid": true,
  "_meta": {
    "lineCount": 1,
    "toleranceApplied": "0.01"
  }
}

Header total off by ten cents fails validation