DEV Community: Iurii Rogulia

The Typography Details Your Visitors Notice Without Knowing Why

Iurii Rogulia — Mon, 21 Sep 2026 10:00:55 +0000

Nobody has ever emailed me to complain about a straight quote where a curly one belongs. Nobody has ever pointed out that a page used an em dash in one paragraph and a hyphen doing the job of a dash three paragraphs later. I doubt more than a handful of visitors to any site could tell you, if you asked directly, what the correct dash even is.

And yet they notice. Not consciously – nobody reads a landing page thinking ‘hm, inconsistent punctuation.’ But somewhere below that, a site that gets these details right reads as made with care. A site that doesn’t reads as assembled, quickly, by whoever was cheapest or fastest. Same words, same layout, same offer – different trust, for a reason the reader couldn’t name if you asked them to.

What ‘Right’ Actually Looks Like

Here’s the same sentence, once with the typography most software leaves you with by default, and once with it corrected for a British-English reader – curly quotes, proper dashes, a real ellipsis character instead of three dots, spacing that respects the punctuation around it:

She asked, "Isn't this the shop they call 'round the corner'?" ... We'd
walked - nearly 3 km - just to find it closed.

She asked, ‘Isn’t this the shop they call “round the corner”?’ … We’d
walked – nearly 3 km – just to find it closed.

Read the first version. It’s fine. Perfectly legible. Nothing about it screams ‘wrong’. Now read the second one right after it. It just sits better – the quotes nest properly instead of fighting each other, the dash reads as a pause instead of a stray minus sign, the ellipsis is one calm character instead of three periods bumping into the next word.

That difference is the whole article. It’s not dramatic. That’s the point: it’s not supposed to be dramatic. It’s supposed to be invisible when it’s right and only faintly, unaccountably ‘off’ when it’s wrong.

Even a Careful Site Gets This Wrong

I didn’t write that before/after pair by hand – it’s real output from a locale-correct typography engine I built and shipped this year, polytypo, which you can run on your own text at polytypo.dev. This week I ran it across every public page of this site, built up over more than a year, one article and one service page at a time.

It caught real inconsistencies I hadn’t noticed while writing any single page: an em dash on one article where the rest of the site used a spaced en dash, straight apostrophes sitting two paragraphs from curly ones, the odd stray hyphen standing in for a proper dash. None of it was wrong on any one page in isolation. It only became visible once something checked every page against the same rule at once. I’d been maintaining this site carefully for over a year and it still drifted – which is exactly the point: this isn’t a mistake careless people make. It’s a category of work nobody notices they’ve skipped until something goes and checks.

The Bigger Pattern This Is Standing In For

Typography is a convenient example because you can see it in one sentence. But it’s a stand-in for a whole category of work that shares its shape: correct, invisible when done, and never on anyone’s feature list. A checkout that recomputes the total instead of trusting the number the browser sent. A webhook handler that doesn’t create a second invoice when the retry arrives. VAT applied correctly for the buyer’s actual country instead of whatever the developer tested with. None of these earn a line in a pitch deck. All of them are the difference between software that was finished and software that was shipped once it looked finished.

I wrote about the bigger, costlier end of that same pattern in what an MVP actually costs – the ‘unglamorous 30%’ that a cheap quote quietly cuts because it doesn’t show up in a five-minute demo. Typography is the smallest, cheapest, most harmless-looking member of that family. Which makes it a useful test: if a team cut corners here, on something this visible and this low-stakes, what are the odds they cut corners on the parts you can’t see at all?

slug="mvp-development"
text="Correctness that doesn’t show up when you’re clicking through a preview – typography, checkout maths, retry safety – is part of how I build a product from the first commit, not a pass added at the end."
/>

Who This Actually Matters To

This isn’t a pitch to sell you typography fixes. It’s genuinely not worth commissioning on its own – whoever builds your site can run this kind of pass for free in minutes, and I’d tell you that even if I sold typography audits, which I don’t.

It matters if you’re trying to read a signal you can’t put your finger on: why one option in a shortlist just feels more trustworthy than the others, on paper equally qualified. It’s rarely one dramatic thing. It’s usually a dozen small things like this one, each individually shrug-worthy, adding up to a read on how much the people building it actually cared about the parts nobody was going to grade them on.

It doesn’t matter if you’re optimising for speed to a rough first version and you know that’s what you’re doing – ship the plain quotes, fix it later, that’s a legitimate call for a prototype nobody’s judging yet. The problem is only when ‘later’ is the plan for the parts a customer’s trust actually rests on, and nobody ever says so out loud.

If you’re trying to tell a genuinely careful build from one that just looks finished on the surface, that’s worth a real conversation before you sign anything. Let’s talk.

How to Spot a Fake Pay Stub: A Reviewer’s Guide

Iurii Rogulia — Mon, 21 Sep 2026 10:00:44 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

If you review pay stubs — screening tenants, underwriting a loan, checking a job applicant’s stated salary — you already have habits for spotting a bad one: you check the math, you look at the fonts, you squint at the alignment. Most of the time those habits work: a rushed forgery has a tell, and after a few hundred stubs the fake ones start to look wrong before you can say exactly why.

This guide collects that visual checklist in one place — the concrete things a reviewer can look for without any special tooling. It also says where that checklist stops working. A well-executed edit to an otherwise genuine pay stub can pass most of this list. That’s not a reason to skip the checklist — most fakes are still sloppy, and catching the sloppy ones by eye saves everyone time. It’s a reason to know what the checklist can’t see, and what does.

The Visual Checklist

Work through these in order. Each one takes seconds, and together they catch a meaningful share of low-effort forgeries.

1. Does the math actually add up?

Gross pay minus deductions should equal net pay, every time, on every line. Add up the year-to-date figures against the stub’s own pay-period math — if the stub shows a bi-weekly pay date, does the YTD gross look like a plausible multiple of the per-period gross for that point in the year? Fabricated stubs are often built by someone typing numbers into a template rather than running them through a real payroll calculation, and the arithmetic doesn’t always reconcile once you check it against itself.

2. Do the deductions make sense for the numbers shown?

Tax withholding, and other statutory deductions where applicable, should sit in a plausible range for the stated gross and the jurisdiction. A stub with a suspiciously round federal withholding, or a state tax line that doesn’t match the address on the document, is worth a second look. So is a stub with no deductions at all beyond taxes — real payroll runs almost always carry at least one benefit or retirement deduction line for a salaried employee.

3. Fonts and alignment

Open the stub at full zoom and look at every number field individually. A genuine payroll export is typographically uniform — a field that was retyped often sits slightly apart from its neighbors: a pixel or two off the shared baseline, a very slightly different font weight, or different character spacing. This is the single most useful thing a careful human eye can catch on a low-effort forgery.

4. Employer details that don’t line up

Cross-check the employer name, address, and any logo against what you can find publicly — a company website, a business registry, a LinkedIn page. A pay stub claiming to be from a company whose registered address doesn’t match, or whose logo is a stretched or low-resolution copy of the real one, is a red flag independent of anything on the numbers side.

5. Formatting that doesn’t match the claimed provider

Most employees are paid through recognizable payroll platforms — ADP, Paychex, Gusto, Workday, or an in-house system — each with a distinctive layout, header style, and footer disclaimer text. If you review pay stubs regularly, you’ll start to recognize these templates. A stub that claims to come from a well-known payroll provider but doesn’t match that provider’s actual layout is worth flagging. Generic “pay stub template” formatting — the kind sold on template marketplaces — has a look of its own once you’ve seen a few.

6. Inconsistent or implausible dates

Check that the pay period, pay date, and year-to-date figures are internally consistent with each other and with the calendar. A pay date that falls on a weekend for a company that pays biweekly on Fridays, or a YTD figure that doesn’t grow correctly across consecutive stubs from the same person, is a signal worth pursuing.

7. File metadata, if you can see it

Some PDF viewers expose basic document properties — right-click and look for “Document Properties” or similar. A stub whose stated creator or producer tool contradicts the claimed payroll provider (for example, a document that claims to be issued by a major payroll platform but whose metadata says it was produced by a generic PDF editor) is worth a second look. This is a coarse signal — plenty of legitimate documents pass through a compression or conversion step for unrelated reasons — but it’s a free check if your viewer shows it.

Where This Checklist Runs Out

Every item above is a content check — it asks whether what’s printed on the page looks right. A well-executed edit to an otherwise genuine pay stub can pass most of these checks.

When a forger works from a genuine document instead of a blank template, the visible layer is inherited rather than recreated — the typography, the employer block, the provider styling, and the surrounding dates were never the part that changed. Nothing on the page has to be rebuilt convincingly, so there’s little for the eye to compare against. A visual review is scoring the parts of the document a careful edit tends to leave alone.

This is the gap between “does this look right” and “was this file changed after it was issued.” Those are two different questions, and a visual review — however careful — is mostly answering the first one.

The Layer That Answers the Other Question

A PDF isn’t just the page you see. It’s a structured file that records how it was built and what happened to it after it was produced. Opening a genuine pay stub and saving an edit usually leaves traces in that internal structure, even when the visible numbers look convincing afterward.

HTPBE is a self-serve API (and a free web check, for a one-off) that reads that structure and returns one of three verdicts, plus a list of named findings describing what it found:

intact — no structural evidence the file was changed after it was created, and nothing in its origin blocks that reading. This isn’t proof the numbers on it are true — it’s the absence of structural evidence that the file was altered.
modified — the file carries structural evidence that it was changed after it was first generated. This is the case a visual check can’t see: the visible page can look untouched while the file itself records that it was not.
inconclusive — the file’s origin doesn’t give us an institutional baseline to check integrity against, which happens with consumer software, online editors, and scanners among others. This isn’t a pass and isn’t an automatic reject — it’s a routing signal. A stub claiming to be from a major payroll platform that comes back inconclusive is worth escalating with an employer confirmation regardless of the reason; a smaller employer running their own payroll often produces this result as a matter of course.

It never asks whether the salary figure is believable — that’s the content-review job the checklist above already does well. It asks whether the file’s own construction shows signs of change after issuance. That makes it additive: it sits alongside employer callbacks, income cross-checks, and the visual review above, covering the one case none of those were built to see — a well-executed edit to an otherwise genuine document.

You can try this directly: drop a pay stub into the free check on this site and get a verdict in a few seconds, no account needed — an intact or inconclusive result comes back as a full report; a modified result unlocks its detected-signal detail once you register. It’s the same engine behind the API, and it’s a fast way to check a single document before deciding whether to escalate it.

What This Doesn’t Solve Either

Two honest limits are worth naming. First, no structural check speaks to whether the numbers on the page are true. Structural analysis answers “was this file changed after it was issued,” not “is this claim real” — a document can be structurally unremarkable and still describe employment or income that never existed. That’s exactly why the visual checklist above stays in the process: content review and structural review answer different questions, and each is blind where the other isn’t.

Second, structural analysis can’t confirm employment or income independently — it can’t tell you the person actually works there or actually earns that amount. It tells you whether the file in front of you was changed after it left whatever system produced it. Employer verification, income cross-checks against bank records, and the visual review above all still matter. The point of adding a structural check isn’t to replace any of that — it’s to close the one gap none of it covers.

Building This Into a Review Process

For teams that want to add this as a routine step rather than a one-off check, the integration is small. Send the stub’s file location to the analyze endpoint:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-storage.example.com/paystubs/applicant-3391.pdf"}'

Fetch the result by the returned ID:

curl https://api.htpbe.tech/v1/result/<check-id> \
  -H "Authorization: Bearer YOUR_API_KEY"

Route on the verdict: modified goes to manual review and a request for a fresh copy pulled directly from the source system; inconclusive branches on the claimed provider, exactly as described above; intact proceeds to your normal content review — the checklist at the top of this guide.

Full documentation, including test keys you can try against sample documents before spending a credit, is at the API reference.

The Short Version

Run the visual checklist first — it’s fast, and it catches most low-effort fakes. Check the math, check the fonts and alignment, check the employer details, check the provider formatting, check the dates. When a stub passes all of that and something still feels off, or when the document matters enough that “looks right” isn’t a good enough bar, add a structural check on top. The two layers catch different things, and neither one replaces the other.

VAT Vendor Verification for Marketplaces

Iurii Rogulia — Mon, 21 Sep 2026 09:00:46 +0000

Originally published at vatnode.dev. The version on vatnode.dev is the canonical source — refer to it for the latest content.

VAT Validation for Multi-Vendor Marketplaces: Who Checks Whom

A marketplace has at least three parties in every transaction – the platform, the vendor, and the buyer – and VAT validation applies differently to each. The short answer to ‘who checks whom’: the platform validates the vendor’s VAT number before onboarding them as a business seller, and separately validates the buyer’s VAT number when a transaction’s tax treatment depends on the buyer being VAT-registered (typically B2B). Same lookup, same underlying source, two different reasons to run it.

The rest covers both sides, where deemed-supplier rules fit without turning this into a tax memo, and how to run the checks at marketplace scale rather than one vendor at a time.

Validating Vendors at Onboarding

Before you list a business as a seller, you want to know their VAT number is real. That means running it through VIES – the EU’s VAT number lookup – and checking two separate things that people conflate:

Format validity – does the string match the country’s checksum pattern? This catches typos instantly and needs no network call.
VIES registration status – is that number actually registered in the issuing member state’s system right now? A number can pass format validation and still not be registered – format is a syntax check, not proof of registration.

A VIES check is evidence a VAT number was registered at the time of the query – not a certification of the vendor’s business or a guarantee it stays valid. It doesn’t tell you the vendor is solvent, trustworthy, or who they claim to be. It tells you a specific VAT number was on the books in a specific country’s system at a specific moment. Treat it as one input to onboarding, not the whole decision.

Company name and address detail in the response varies by country – some national databases return a full trader name and address alongside the valid/invalid flag, others return only the flag. Don’t build a vendor-matching workflow that assumes every country hands back a name to compare against your KYB records; for enriching a VAT number with company data beyond what VIES itself returns, you may need a country-specific source on top.

Two prefixes worth getting right before they cost you a support ticket: Greece uses EL, not GR, and Northern Ireland uses XI – goods only, since VIES doesn’t cover Northern Ireland services.

Validating Business Buyers

The other side of the same endpoint: when a buyer claims to be a VAT-registered business and the transaction’s treatment depends on that, you check their number too. What that treatment actually is depends on what’s being sold.

For cross-border B2B services, the customer typically self-accounts for VAT under reverse charge (Article 44 place-of-supply, Article 196) when the seller isn’t established in the buyer’s country. For cross-border B2B goods, the mechanism is legally different even though people also call it ‘reverse charge’ colloquially – it’s an exempt intra-Community supply on the seller’s side (Article 138) paired with the buyer’s intra-Community acquisition (Articles 2(1)(b) and 20). The two aren’t interchangeable, and a marketplace selling both goods and services shouldn’t blur them into one workflow.

Either way, the buyer’s VAT number being valid is necessary but not sufficient. The transaction facts – what’s sold, to whom, under what terms – have to actually support the treatment. Validation alone never proves eligibility for reverse charge or zero-rating; it’s one condition among several. For a fuller breakdown of when a check is actually load-bearing for a transaction, see when to validate a VAT number.

Deemed Supplier: Where the Platform Itself Gets Pulled In

There’s a separate wrinkle specific to marketplaces, worth naming even though it’s outside VAT number validation itself. In some fact patterns, EU VAT law shifts VAT liability onto the platform – the ‘deemed supplier’ rules under Article 14a of the VAT Directive. They apply to specific scenarios: certain imported low-value goods, and goods sold within the EU by a non-EU-established seller through an electronic interface. It’s goods, not services, and the scope isn’t static – the rules have evolved and may again.

This is not tax advice – whether deemed-supplier rules apply to your marketplace depends on your specific goods, seller locations, and transaction flow. Talk to a tax adviser before relying on this for compliance decisions. Vendor VAT validation and deemed-supplier liability are two different questions; solving the first doesn’t answer the second.

Audit Evidence, at Marketplace Scale

A marketplace doesn’t run one VAT check – it runs one per vendor onboarded and, depending on volume, one per qualifying transaction. When an auditor asks you to justify why a vendor was treated as a valid business seller, or why reverse charge was applied to a specific buyer, ‘we looked at VIES once’ isn’t a record – a stored, timestamped result is.

VIES can return a VIES consultation number on a requester-qualified lookup: a timestamped reference showing a specific check happened at a specific moment. Some tax authorities (French and German practice, notably) look for it on audit. It is not a tax certification and it doesn’t adjudicate any specific transaction – it’s contemporaneous proof the lookup occurred, nothing more. It’s also not unique to any one provider; several VAT APIs return it. What actually differs between providers is how much friction it takes to get one on every check.

On vatnode, that friction is one-time: set your requester VAT once in dashboard Account details, and every vendor or buyer check – single or bulk – automatically gets a consultation number when VIES issues one, with no per-call parameter to wire into your integration. A requester-authenticated call uses VIES directly rather than falling back to a national source, because the consultation number is VIES-specific evidence; a national registry can’t produce it.

Every response also carries a source field – VIES, CACHE, or a national code – so you always know which system actually answered, and a consultationNumber field that’s always present as a key even when its value is null because VIES didn’t issue one for that check. That’s the accurate version of ‘never-null’: the field is always there for your code to read, not that every check magically succeeds.

Ongoing Monitoring Across Many Vendors

A VAT number valid at onboarding can lapse or deregister at any point after. That’s true for a single supplier relationship, but a marketplace with hundreds of vendors has hundreds of independent places where it can happen without anyone noticing – no vendor is going to volunteer that their VAT registration was cancelled.

There’s no legally mandated re-check interval; this is operational risk management, not a compliance clock. The practical pattern is to validate at onboarding and then monitor vendor VAT IDs on a schedule that matches your exposure, rather than treating the onboarding check as permanent proof. VAT monitoring that pushes a webhook when a previously-valid number goes invalid means you find out when it happens instead of during your next audit.

Doing This in Code

The endpoint is the same for a vendor onboarding check and a buyer check:

curl https://api.vatnode.dev/v1/vat/DE123456789 \
  -H "Authorization: Bearer $VATNODE_API_KEY"

The response includes valid, vatId, countryCode, countryName, companyName, companyAddress, checkId, verifiedAt, source, and consultationNumber. If the call fails upstream, you get a typed error instead – VIES_UNAVAILABLE (503), VIES_ERROR (502), UPSTREAM_TIMEOUT (504), RATE_LIMITED (429), or INVALID_FORMAT (400) if the string never had a shot at being a real VAT number. A marketplace onboarding flow should treat those as ‘try again’ states, not silently reject a vendor because VIES had a bad moment.

A vendor roster or a buyer list at any real marketplace volume is a bulk VAT validation workload, not a loop of single calls – submit the whole roster as one job and poll it. The job paces its own concurrency against VIES, so you’re not the one deciding how hard to hit the endpoint. Vendors and buyers also span a lot of countries fast for any marketplace with real reach; check country-by-country coverage for where national fallback applies. For a subset of member states, if VIES itself is temporarily down, vatnode falls back to that country’s own tax authority or company-registry API so you still get an answer – except on a requester-authenticated call, where fallback is disabled because the consultation number is VIES-only evidence.

If your marketplace is itself a SaaS platform selling to EU business buyers, EU VAT for B2B SaaS covers your own reverse-charge obligations separately from what you check on your vendors. And if you’re weighing whether to query VIES directly instead of through an API, a production VIES alternative covers what ‘just call VIES’ leaves out once you’re doing it for hundreds of vendors instead of one.

Coverage spans the EU-27 plus XI for goods, including German VAT numbers, French VAT numbers, and Dutch VAT numbers.

This is general information about EU VAT and VIES, not tax advice. Whether reverse charge, deemed-supplier rules, or any specific tax treatment applies to your marketplace depends on facts we can’t assess here – confirm your own obligations with a qualified tax adviser.

FAQ

Does a marketplace have to validate seller VAT numbers?

VIES itself doesn’t mandate anyone check anything – it’s a lookup service, not a legal requirement. But validating a business vendor’s VAT number is the standard due-diligence step before onboarding them or applying reverse charge to their transactions, and it’s what an auditor will expect to see. This isn’t legal advice – confirm your own obligations with a tax adviser.

How often should a platform re-check vendor VAT IDs?

At onboarding, at minimum. A number valid at signup can lapse or be deregistered later, and a marketplace with hundreds of vendors has hundreds of independent points where that can happen unnoticed. There’s no legally fixed re-check interval – treat periodic re-validation as operational risk management, not a compliance deadline, and consider monitoring vendor VAT IDs on an ongoing basis rather than only at onboarding.

Does vatnode validate both vendors and buyers on a marketplace?

Yes – the same GET /v1/vat/:vatId endpoint checks any EU VAT number, vendor or buyer. vatnode doesn’t distinguish between roles; the marketplace decides which party’s number it’s checking for a given transaction and calls the endpoint accordingly.

What about deemed-supplier VAT rules for marketplaces?

In some fact patterns, EU VAT law shifts VAT liability onto the platform itself – the ‘deemed supplier’ rules under Article 14a of the VAT Directive. Whether they apply depends on your specific goods, seller locations, and transaction flow, and the rules only cover certain scenarios (not every marketplace transaction). This isn’t tax advice; talk to a tax adviser before relying on this for compliance decisions.

Validate vendors and buyers from one API

Check a vendor or buyer VAT number free right now with the VAT number checker – no account needed. Running it across your vendor roster? Get a free API key and validate through the EU VAT validation API – the free plan (100 requests/month, no card) is enough to wire up the integration and test it against real vendors. A live marketplace roster runs past that fast, so see pricing for where that volume actually lands.

Caching VAT and FX Rates at Build Time, Not on the Request Path

Iurii Rogulia — Fri, 18 Sep 2026 10:00:58 +0000

Two ways to get exchange rates or VAT tables into an application, and both are wrong in a familiar way. Call a rates API on every request or every checkout, and you’ve added latency plus a new third-party dependency to a path where a customer is trying to pay you money. Or hardcode a { GBP: 0.86, CHF: 0.94 } object in source once, and it drifts from reality the moment the ECB updates its reference rates – silently, because nothing breaks when a number is merely wrong.

A third option avoids both failure modes. It’s the one I used on a B2B e-commerce project I built – a Next.js storefront selling across 32 European markets (the project card covers the broader VAT and payments architecture). Fetch the rates once, at build time, cache them to a committed JSON file, and let the running application read that file instead of the network. Here’s the script and the reasoning behind each of its decisions.

The Prebuild Script

The relevant file is scripts/fetch-fx-rates.js, a prebuild step that runs before next build and nowhere else:

// scripts/fetch-fx-rates.js
const fs = require("fs");
const path = require("path");
const OUTPUT_FILE = path.join(__dirname, "../src/data/fx-rates.json");

const TARGET = ["GBP", "CHF", "NOK", "PLN", "CZK", "DKK", "SEK", "RON", "HUF", "TRY"];

async function fetchRates() {
  const url = `https://api.frankfurter.app/latest?from=EUR&to=${TARGET.join(",")}`;
  const res = await fetch(url);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const data = await res.json();

  const rates = {};
  for (const cur of TARGET) {
    const r = data.rates[cur];
    if (typeof r !== "number") throw new Error(`missing rate for ${cur}`);
    rates[cur] = r;
  }

  const output = {
    generatedAt: new Date().toISOString(),
    base: "EUR",
    source: "ECB via frankfurter.app",
    note: "Approximate reference only. Checkout charges in EUR.",
    rates,
  };

  fs.writeFileSync(OUTPUT_FILE, JSON.stringify(output, null, 2) + "\n");
}

fetchRates().catch((err) => {
  console.error("❌ FX fetch failed:", err.message);
  console.error("   Keeping the committed fx-rates.json as-is.");
  process.exit(0); // Don't fail the build
});

frankfurter.app mirrors the European Central Bank’s daily reference rates, needs no API key, and returns exactly the ten non-euro currencies this storefront ships to. The script fetches EUR-to-X for all ten in one request and writes the result to src/data/fx-rates.json, which is committed to the repo like any other source file.

That JSON feeds one thing: a small, clearly labeled UI hint next to a EUR price for a non-euro shopper – ‘≈ £25’ next to ‘€29’. It is never the transactional amount. The checkout itself still charges in EUR regardless of which country the buyer is in; the FX number is a courtesy conversion so a UK buyer has some sense of what €29 means without doing the math themselves. That sets how fresh this data actually needs to be.

‘Never Fails the Build’ Is the Load-Bearing Line

Read the .catch() block again. On any failure – frankfurter.app is down, rate-limited, returns a malformed payload, or the network blips in CI – the script logs the error, leaves the already-committed fx-rates.json untouched, and calls process.exit(0). Exit code zero. As far as the shell and the CI pipeline are concerned, the prebuild step succeeded.

The alternative is to throw and let a failed fetch fail the whole build. That sounds more correct – if the data is stale, don’t ship – until you look at what actually triggers this build. Every deploy does: a copy fix, a new blog post if content lives in the same repo, an unrelated bug fix in checkout logic that has nothing to do with currency conversion. Tie all of that to the uptime of a third-party FX API, and a transient 503 from frankfurter.app on a Tuesday afternoon blocks a hotfix that has nothing to do with FX rates.

Shipping a build with FX numbers a day, or a week, old is the cheaper failure. The fallback here isn’t ‘no data,’ it’s yesterday’s real data instead of today’s real data. The committed JSON was itself fetched from the same source at some previous build, so it degrades to slightly stale rather than to zero. A hint that’s approximate by design tolerates that easily. A deploy pipeline tolerates a new external dependency on its critical path much worse.

Same shape of decision as retrying a webhook call versus failing it outright. The useful question is what failure actually costs here, and whether blocking the whole pipeline is proportionate to that cost. For a display-only currency hint, it isn’t.

Dev Mode Never Touches the Network for This

The prebuild hook only runs on npm run build. npm run dev never invokes fetch-fx-rates.js at all – it just reads whatever fx-rates.json is already sitting in the repo, committed with sane values. The omission is deliberate. A local dev session doesn’t need today’s GBP rate to be accurate to the fourth decimal place to build a checkout page. It needs a plausible number so the UI renders correctly, and it needs that without a network call that can fail, rate-limit, or simply add a few hundred milliseconds to every cold start.

The stronger reason is one most caching write-ups skip: a build script that hits an external API gives local development a network dependency that has nothing to do with the feature you’re working on. Committing the cache file removes that dependency entirely for the vast majority of work sessions that aren’t specifically about the FX integration.

VAT Rates: Same Instinct, Different Failure Direction

The VAT side of the same project makes the identical build-time trade – but pairs it with the opposite default on unknown input. VAT rates come from getAllRates() in eu-vat-rates-data, a package I publish that mirrors the European Commission’s VAT data (the pipeline that keeps it current is its own story, covered in Publishing One Package to Five Registries with GitHub Actions). No live call to a tax authority on checkout – the rate for every EU member is bundled into the deployed app at build time, versioned through the package’s dataVersion:

// src/lib/pricing/config.ts
const packageRates = getAllRates();

export const VAT_RATES: Record<string, VatRateInfo> = {
  ...Object.fromEntries(
    Object.entries(packageRates).map(([code, data]) => [
      code,
      { name: data.country, rate: data.eu_member ? data.standard / 100 : 0 },
    ])
  ),
  US: { name: "United States", rate: 0 },
};

export const RATES_UPDATED_AT = dataVersion;

export function getVatRate(countryCode: string): number {
  const rateInfo = VAT_RATES[countryCode];
  if (rateInfo !== undefined) return rateInfo.rate;
  if (countryCode in ZERO_VAT_TERRITORIES) return 0;
  // Fail fast on a fully unknown code rather than silently charging 0% VAT.
  throw new Error(`getVatRate: unknown country code "${countryCode}"`);
}

Here the design intentionally does not fall back the way the FX script does. getVatRate throws on a country code that isn’t in the bundled table and isn’t in an explicit, named ZERO_VAT_TERRITORIES exception list (Åland, a served country that’s simply absent from the VAT-rates package’s data). That asymmetry is the point, not an inconsistency: an approximate FX hint failing over to ‘yesterday’s number’ costs nothing but precision. A VAT calculation silently failing over to 0% costs money – either undercharged tax that the seller owes, or, worse, a shipped default that nobody notices until a filing is wrong. Same build-time caching on both sides of this codebase, opposite failure behavior, because the two data points have opposite blast radii when they’re wrong. This checkout flow’s actual VAT and currency math at request time – how the cached numbers get applied and re-verified server-side – is a separate story from the caching mechanism itself.

Where a Build-Old Number Is Fine, and Where It Isn’t

The cost is staleness. The rates in fx-rates.json are as fresh as the last successful npm run build, not as fresh as the last minute. For this project that’s a non-issue twice over: the FX number is explicitly a display-only hint, never the charged amount, and standard VAT rates change on the order of once a year through a legislated, announced process, not intraday.

In a different context it stops being fine. A system that actually settles in the converted currency – an FX trading desk, a multi-currency ledger reconciling against real bank movements – cannot tolerate a build-old rate. That’s a request-time, ideally streaming, problem, and treating it as a build artifact would be a genuine bug rather than a trade-off. VAT has its own version of this: a country raises or lowers its standard rate on a known effective date, the last build ran the evening before, and the deploy lands after midnight. Then ‘rebuild before the rate changes’ becomes an actual operational task, and this pattern can’t paper over it. This project doesn’t have that problem, because the number it caches is a hint rather than a settlement and the tax table it caches changes on a calendar that a normal deploy cadence easily outpaces. That’s a property of this specific system, not a property of build-time caching in general.

The Alternative Nobody Admits to Shipping

The pattern this replaces is usually not ‘call the API live.’ More often it’s a const rates = { GBP: 0.86, CHF: 0.94, ... } committed once during initial development and never touched again, because nothing forces anyone to touch it. No build step fails, no test catches it, no dashboard flags it – the numbers are just quietly wrong, more wrong every month, until a customer complains that the displayed conversion looks off, or a VAT filing gets flagged. A committed JSON that a script refreshes on every build looks identical to a hardcoded object at rest – same file, same shape, no runtime cost – but it doesn’t rot, because refreshing it is a side effect of the thing you were going to do anyway: ship.

The same move – take a slow-changing computation out of the request path and into the build, so the running app never pays for it and nobody has to remember to redo it by hand – shows up elsewhere on this stack, for a completely different kind of data. This site’s own related-posts graph is computed by a generate-relations.ts script that runs as a codegen step in the same next build chain, before the framework build starts. Different problem – internal content relationships, not external API data – but the same reasoning: if a value doesn’t need to be correct to the second, compute it once when you’re already deploying, not on every page load.

If you’ve got a rates table, a tax lookup, or any other slow-moving external data sitting in your request path out of habit rather than necessity, get in touch and let’s find out whether it belongs at build time instead. That’s the kind of workflow automation covered on the Automation & Workflows page.

Further reading:

Publishing One Package to Five Registries with GitHub Actions – how eu-vat-rates-data, the package behind the VAT table in this article, stays current with zero manual steps
A Typed MDX Content Pipeline with Velite (Next.js Tutorial) – this site’s own build-time codegen step, a different kind of ‘compute it once, not per request’
pi-pi.ee – B2B E-commerce for Waterless Urinal Systems – the project this VAT and FX caching pattern is drawn from

Do Mortgage Underwriters Actually Verify Bank Statements?

Iurii Rogulia — Fri, 18 Sep 2026 10:00:44 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

Yes – and more thoroughly than most borrowers expect. A mortgage file is one of the most heavily documented things in consumer finance, and the asset side of it has its own apparatus: sourcing rules for unexplained deposits, a form the bank itself fills in, and an automated path where a vendor pulls account data straight from the institution. Underwriters are not glancing at a balance and moving on.

But ‘verify’ in mortgage underwriting means something specific, and it is worth being precise about it. The apparatus verifies whether the money is real, where it came from, and how long it has been there. On the path where the borrower uploads a PDF, none of it asks whether that PDF is the file the bank produced. Those are separate questions, and the second one sits outside the checklist entirely.

This is a walk through what each asset-verification control actually establishes, which ones bypass the borrower’s document altogether, and what remains unverified on the path where the document is all you have.

What the Asset File Is Actually Made Of

Asset verification in a conforming mortgage is not one check. It is a small stack of them, and which ones appear in a given file depends on how the assets were documented.

Bank statements, read for sourcing and seasoning

The default is the statement itself, usually the most recent two months for each account being used toward down payment, closing costs or reserves. The underwriter is not reading it for the closing balance alone. The work is in the deposits.

Under Fannie Mae’s depository-account guidance, a large deposit is a single deposit exceeding 50% of the total monthly qualifying income for the loan, and large deposits on a personal account have to be evaluated. If the money cannot be sourced – traced to a documented, acceptable origin – it does not count toward the funds the borrower is required to have. The point is not that a big deposit is suspicious in itself; it is that an undocumented lump sum might be a borrowed loan the file does not know about, which would change the debt-to-income ratio the approval rests on.

Alongside sourcing sits seasoning: money that has been in the account across the documented period needs no explanation, which is why ‘two months of statements’ is the unit. A borrower with funds already sitting there for the full window has nothing to source.

This is genuine verification work. What it verifies is the plausibility and provenance of the money. It reads the numbers on the page and asks whether a real account could have produced them.

The Verification of Deposit

Where statements are thin, contested, or simply not obtainable, the lender can go to the bank directly with a Verification of Deposit – Fannie Mae Form 1006 – which the depository institution completes and returns.

This one is different in kind, and it matters for the argument here: a VOD is issuer-side evidence. The lender is no longer reading the borrower’s copy of anything. It is asking the bank what the balance is.

It also has a documented weakness that shows how carefully these controls are actually specified. A VOD reports balances, not necessarily depository activity. When activity is not included, the guidance still requires the lender to verify the source of funds for accounts opened within 90 days of the application and for balances considerably above the average the VOD reports – because a snapshot of a balance cannot tell you how the balance got there. The control knows its own limits.

Employment and income, cross-referenced

The asset file does not stand alone. A Verification of Employment confirms the borrower’s job and income with the employer, and the 4506-C authorises the lender to pull tax transcripts from the IRS through the IVES programme. Those are income controls rather than asset controls, but they cross-reference the statement: deposits that are supposed to be payroll should match what the employer and the transcripts say the borrower earns.

The tax side has its own timing characteristics – the transcript comes back days after the file has already moved – and we have written that up separately in fake tax return and transcript fraud. The income-document side, where the paystub or W-2 is the artefact being altered, is covered in altered paystubs and W-2s.

The automated path, where the document disappears

The most interesting control is the one that removes the PDF from the process.

Both GSEs run automated asset assessment. Fannie Mae’s Day 1 Certainty uses the Desktop Underwriter validation service; Freddie Mac’s Asset and Income Modeler works inside Loan Product Advisor. In both, the lender does not receive a borrower-supplied statement at all. A third-party service provider retrieves account data directly from the financial institution and delivers it as a verification report, and the automated underwriting system assesses that data.

The reason lenders adopt this is commercial rather than forensic: eligible loans receive relief from certain representations and warranties on the validated data, which means the lender is not on the hook for a repurchase if that component later proves wrong. Freddie Mac has extended the account-data path across income, assets and, more recently, additional asset types and sources of funds.

For the loans that run this way, the question this article is about does not arise. There is no borrower-supplied file, so there is nothing to alter. This is the strongest control in the stack and it should be used wherever it can be.

Where the PDF Path Survives

The automated path is not universal, and the cases where it is unavailable are not random. They correlate with exactly the borrower profiles where document fraud concentrates.

Institutions the vendor cannot reach. Account-data coverage is wide but finite. Smaller credit unions, some regional institutions and most foreign banks are not connected.
Foreign and cross-border assets. A borrower whose down payment sits in an overseas account is documenting it with statements, full stop.
Borrowers who decline to connect. Consent is required. Some applicants refuse on privacy grounds, some out of friction, and some because a direct pull would show something the document does not.
Third-party accounts. A gift donor is not the lender’s borrower and typically will not be connecting an account to anyone’s verification service. The donor statement arrives as a PDF, and it is the least examined document in the file – a case worth its own treatment, which it gets in mortgage gift letter fraud.
Non-agency and portfolio products. Bank-statement loan programmes for self-employed borrowers are built on statements by design, sometimes twelve or twenty-four months of them.

On every one of these files, the asset evidence is a document the borrower obtained and handed over. And a borrower who intends to change a number will end up on this path, because it is the only path where changing a number accomplishes anything.

The Question the Stack Does Not Ask

Line the controls up and the common thread is visible.

Control	What it establishes	Does it inspect the borrower’s file?
Large-deposit sourcing	Where an unexplained deposit came from	No – it reads the numbers
Seasoning	How long funds have been in the account	No – it reads the numbers
VOD (Form 1006)	Balances, confirmed by the bank	No – it goes around the file
VOE / 4506-C	Income consistency from employer and IRS	No – different documents
Automated asset report	Account data pulled from the institution	No – there is no file

Nothing in that column inspects the document. Where a control is strong, it is strong because it bypasses the document and goes to the source. Where the source is unreachable and the document is all there is, the controls fall back to reading the content – sourcing, seasoning, arithmetic, cross-reference.

Reading content is a real check and it catches real fraud. It catches the borrower whose fabricated deposits do not match the pay cycle, whose balance column stops reconciling, whose lump sum has no story. What it cannot catch is the case where the content was tuned to pass it. A borrower who downloads a genuine statement, opens it in an editor and changes one figure gets to see the checklist in advance. They can recompute the running balance so it still reconciles, pick a deposit that fits the stated pay cycle, and avoid the tidy round numbers that draw attention. The file that arrives is the bank’s real template, with the bank’s real logo, in the bank’s real typography, containing one number that is not the bank’s.

Nothing on the underwriting checklist asks whether that file was edited after the bank issued it. Not because the checklist is careless – because it was built to verify money, not files. The general-lending version of the same gap, outside mortgage’s guideline apparatus, is set out in how lenders verify bank statements.

The Residual Question: Was the File Changed After Issue?

A PDF is not a picture of a page. It is a structured file that carries an internal record of how it was assembled and what was done to it afterwards – which software wrote it, how many times it was written to, whether a signature covers the bytes. Opening a genuine statement, editing it and saving it generally leaves traces in that record, and those traces do not depend on whether the visible numbers are plausible.

That record is not something retyping makes agree. Recomputing a balance column so it still reconciles is an operation on the page; it says nothing about how the file came to exist.

HTPBE reads that structure and returns one of three verdicts. intact means no structural evidence of post-creation change, with an origin consistent with a single-pass institutional export – the absence of evidence of change, not proof the numbers are true. modified means the file carries structural evidence that it was written to after it was first generated; named modification markers such as HTPBE_EDITING_TOOL_FINGERPRINT, HTPBE_MULTIPLE_REVISION_LAYERS or HTPBE_DATES_DISAGREE describe what was found. inconclusive means the file’s origin – consumer software, an online editor, a scanner – leaves no institutional baseline to check integrity against.

On mortgage assets, inconclusive earns its place rather than being a shrug. A statement the borrower says came straight out of a major retail bank’s online banking, arriving with a consumer-software origin, has a provenance question attached to it that is worth asking before the file moves. The same verdict on a scanned statement from a small credit union is unremarkable. The verdict is the same; the action depends on what the document claims to be. It is unpacked properly in what inconclusive actually means.

What This Layer Is Not

This is a file-integrity layer that sits alongside sourcing, seasoning, the VOD, the VOE, the 4506-C and automated asset assessment – not a substitute for any of them, and not a shortcut around agency documentation requirements. A structural verdict is not a verification of deposit, does not evidence assets, does not satisfy any GSE documentation standard, and carries no representation-and-warranty relief. Where the automated account-data path is available, use it; it is a stronger control than anything that can be learned from a file, because it does not involve a file.

Two limits are worth stating plainly.

It says nothing about whether the numbers are true. A file can be structurally unremarkable and describe an account that never held that balance. Content checks and source verification stay in the process; they are answering a different question.

And it has little to say about a document that was never derived from a real statement at all. Where a statement is built from scratch rather than edited, there is no modification event to find. Depending on what produced it, such a file can come back inconclusive or even intact – and intact means only that there is no structural evidence of change, never that the contents are true. That fabricated-from-scratch case is precisely what the VOD and the automated asset report handle well, which is the argument for having both layers rather than choosing between them.

Nor is a structural finding a decision about a person. It is a reason to go back to the source: ask for a copy pulled directly from the bank’s portal, order the VOD, or route the file to a human who will.

Wiring It Into an Asset Review

For a one-off document, this needs nothing but the file. Register and you can upload a statement here for a verdict in a few seconds; new accounts come with five checks, and beyond that it is pay-per-check.

At origination volume, it belongs at intake rather than at the underwriter’s desk. The integration is two calls: one to submit the document URL, one to fetch the verdict and named markers as structured data. Run it the moment an asset document lands in the loan file, before anyone reads it, and route on the outcome – modified to manual review and a request for a fresh copy from the source; inconclusive branched on what the document claims to be; intact through to the sourcing and seasoning work the checklist above describes. Store the check identifier against the loan record so the result is retrievable if a decision is ever reviewed. Endpoints, response shape and test key scenarios for building against it are documented in the API reference, and the document-type walkthrough lives on the fake bank statement detection page.

Mortgage underwriting verifies bank statements carefully, and where it can reach past the document to the institution it verifies them very well indeed. The gap is not in the diligence. It is that on the files where the document is the only evidence, no one is asking whether the document is the one the bank issued.

What Happens When You Reverse-Charge an Invalid VAT Number

Iurii Rogulia — Fri, 18 Sep 2026 09:00:46 +0000

Originally published at vatnode.dev. The version on vatnode.dev is the canonical source — refer to it for the latest content.

What Happens When You Reverse-Charge an Invalid VAT Number

Short answer: the exposure lands on the seller. If you issue a zero-rated, reverse-charge invoice because the buyer gave you a VAT number, and that number turns out to have been invalid at the time of supply, a tax authority can reassess the transaction as a normal domestic one. You didn’t charge VAT. Now you’re the one who owes it – plus interest, plus whatever penalty regime applies where you’re established.

That’s the mechanical answer. The more useful one is where the actual risk sits, because it usually isn’t ‘the number happened to be bad.’ It’s not validating at all, validating in a way you can’t reproduce later, or being unable to produce the evidence when someone asks for it. This post separates those two stories, because they get conflated constantly and that leads to bad decisions – treating every later deregistration as a crisis, or treating a validated-but-informal check as good enough.

Reverse charge is a services mechanism, not a goods one

Worth being precise here, because the term gets used loosely. In the strict, technical sense, ‘reverse charge’ is Article 44 (place of supply) and Article 196 (customer liable) of Directive 2006/112/EC – and it applies to services. The customer, not the supplier, is the person liable for the VAT.

The goods equivalent looks similar in effect – no VAT on the invoice – but it isn’t the same mechanism. A cross-border intra-EU supply of goods is a zero-rated exempt supply under Article 138, paired with the buyer’s intra-Community acquisition under Article 20. There’s no ‘customer liable’ flip; the exemption and the acquisition are two separate legal events. Calling that ‘goods reverse charge’ is common shorthand, but it isn’t the technical term, and conflating the two conditions can cost you the exemption on one side while you’re checking the wrong box on the other.

This post is scoped to the services case – Article 196. If you’re dealing with the goods side, the reverse-charge concept guide covers both mechanisms properly, and by-country invoice wording is the reference for what to print on the invoice either way.

One reason the distinction matters here:

Since 1 January 2020 (the ‘quick fixes’ under Council Directive (EU) 2018/1910), a VIES-valid customer VAT number stopped being a merely formal condition of the Article 138 goods exemption and became a substantive one. Before that, Plöckl (C-24/15) treated a missing or wrong VAT number as something that shouldn’t defeat the exemption on its own if the substance was there; since 2020, a bad number can defeat it directly.
Article 138(1a) makes the exemption conditional on correctly reporting the supply on the recapitulative statement (EC Sales List) – a valid number isn’t enough if the transaction isn’t reported right.

Both are goods-side rules. They raise the stakes generally, and they’re the reason ‘just eyeball the number’ was never a great practice even before the services case, which never had the pre-2020 formal/substantive distinction to begin with – Article 196 liability has always turned on the buyer actually being a taxable person, valid number or not.

What ‘invalid’ actually costs the seller

This is general information about how EU VAT rules and CJEU case law generally operate. It is not
tax or legal advice, and it isn’t individualized to your facts. If you’ve already issued an
invoice against a number that turned out to be invalid, talk to a qualified adviser in the
relevant jurisdiction before you decide how to fix it.

If a services supply didn’t qualify for reverse charge – because the buyer wasn’t a taxable person, or the VAT number given was never valid – the seller is the one exposed. The tax authority in the seller’s member state can assess the supply as domestic, meaning the seller owes the VAT that should have been charged in the first place. On top of the principal amount, expect interest for the period the VAT went unpaid, and a penalty. National law sets both the interest rate and the penalty percentage, and they vary by member state – there’s no single EU-wide figure to quote here, and treat any source that gives you one flat number as wrong. Assessment and limitation periods are national law too, which is part of why the evidence question below matters: you may need to defend a supply years after you made it.

None of that is contingent on intent. A seller who genuinely believed the number was valid can still end up assessed – the good-faith question (next section) is about whether that assessment is the end of the story or whether there’s a viable defence against it. They’re different questions.

The good-faith defence – and its limits

CJEU case law gives suppliers real protection here, but it’s a defence you have to make out on the facts, not an automatic pass. Teleos (C-409/04), Netto Supermarkt (C-271/06), and Euro Tyre (C-21/16) collectively establish that a supplier who took every reasonable measure available and had no part in fraud can generally keep an exemption even where the evidence later turns out to be false. Be precise about their reach, though: these were decided on the goods exemption (Article 138) and the export exemption (Article 146), not on Article 196 services liability. Applying the same reasonable-measures, good-faith principle to the services case is an extension by analogy of general EU-law principles the Court has applied consistently across VAT provisions – not a services-specific holding. It’s a meaningful protection either way, but it’s built on ‘reasonable measures’ and ‘no involvement in fraud’ – both fact questions a tax authority or court has to be satisfied of, not a checkbox.

Where this gets specifically relevant to invalid numbers: the fact pattern of ‘we checked, it was valid, it was deregistered afterward’ doesn’t have a CJEU ruling squarely on point that says a validated-then-later-deregistered number is automatically covered. The reasonable inference from Teleos and the line of cases after it is that a genuine, dated, requester-qualified check at the time of supply is the kind of ‘reasonable measure’ the case law is talking about – but that’s an inference from the general principle, not a decided rule for this exact scenario. If it matters for a real supply you’ve made, that’s a question for an adviser who knows your jurisdiction, not a blog post.

This is also where the two risk stories diverge:

The number was invalid at the time of supply. You didn’t meet the condition. The good-faith defence might still apply depending on what checks you ran, but you’re starting from a failed condition and arguing your way out of liability.
The number was valid at the time of supply and deregistered afterward. You met the condition when it mattered. The implementation checklist puts it plainly: that’s not your problem at the moment of supply, provided the validation was genuine at the time – the audit position is ‘valid when checked,’ not ‘still valid today.’ Keep the original evidence; don’t let a later status change rewrite what you knew when you issued the invoice.

Those are not the same conversation, and treating the second as if it were the first is how teams end up either panicking over routine churn or, worse, assuming no check is ever really ‘safe’ and giving up on validating at all.

Format-valid is not the same as registered

A VAT number can pass a regex and checksum and still not be registered, or no longer be registered. Format validation tells you the string is shaped correctly – it says nothing about whether the business behind it is VAT-registered right now. VIES is the system that answers that question – a real-time search over the national tax databases of each member state; the Commission doesn’t operate those databases itself, and VIES has downtime, particularly on specific national nodes. A VIES-valid result is a snapshot: it proves the number was valid at the moment you asked, nothing further forward or backward in time.

That snapshot nature is precisely why a dated, requester-qualified check matters more than an undated one. A requester-qualified VIES lookup returns a consultationNumber – a reference VIES itself issues, tying the check to a specific number, requester, and timestamp. It’s evidence you ran the check, not a guarantee the underlying transaction was correct, and it’s only present on requester-qualified lookups – a plain check or a national-fallback result won’t carry one. The business case for keeping it is covered in the consultation number for finance teams; it’s not unique to any one provider, and no provider’s internal ID is a substitute for it. You can generate that same requester-qualified check yourself by calling VIES’s checkVatApprox operation directly – build vs buy is the honest accounting of what maintaining that path actually costs.

Country coverage adds another wrinkle, and it’s easy to get wrong. When VIES is unreachable for a member state, some checks can fall through to a genuine national fallback – a tax authority’s own VAT register that can independently confirm a number. Others have only a company registry, which vatnode does not treat as a validity fallback at all: a business can be active and in good standing in a company registry without being VAT-registered for intra-EU purposes, so registry presence can’t stand in for a VAT verdict. Where only a company registry exists, a VIES outage surfaces as an error, not a substitute ‘valid.’ And even where a real fallback answers, a fallback ‘valid’ is not equivalent to a VIES-valid result for the condition reverse charge actually needs. Which countries fall in which bucket changes over time – see current coverage rather than assuming a fixed list.

What an invalid result actually looks like – and why it’s useful

A GET /v1/vat/:vatId call against a number that isn’t registered doesn’t error. It returns HTTP 200 with valid: false, and it still carries the source, timestamp, and check ID (the consultationNumber below is populated because the account has a requester VAT set):

{
  "valid": false,
  "vatId": "DE123456788",
  "countryCode": "DE",
  "source": "VIES",
  "verifiedAt": "2026-09-04T10:22:31Z",
  "checkId": "01926a3e-9f4c-7c2e-8b1a-3d7e6a2f9c11",
  "consultationNumber": "WAPIAAAAX9999999"
}

That’s a definitive negative, not a failure state, and it’s protective – it’s the artefact that lets you correctly decline to zero-rate the invoice in real time, before the supply happens, rather than finding out during an audit two years later. Contrast that with a VIES outage: VIES_UNAVAILABLE (HTTP 503) or a national MS_UNAVAILABLE doesn’t mean invalid, it means the check didn’t run – see handling VIES downtime and the error reference for how to handle it without either blocking the customer or silently charging VAT on a transient outage.

Where the actual exposure comes from

The real risk isn’t ‘a customer’s VAT number went bad.’ It’s one of these:

Never validating. Taking the number at face value because it’s the right length and shape.
Validating without a reproducible, dated, requester-qualified check. An undated internal note or an ad-hoc lookup with no requester attached gives you a weaker evidentiary position than a check that VIES itself timestamped.
Not being able to produce the evidence later. A check you ran but didn’t store – or stored without linking it to the invoice it supports – is functionally the same as not having checked, from an auditor’s point of view. When to validate a customer’s VAT number covers the triggers; the full audit trail covers what to keep and for how long.

The practical defence against all three is the same: validate at the point where the treatment is decided, keep the dated evidence next to the invoice, and re-check periodically rather than assuming a signup-time validation holds forever. Bulk re-validating a customer base is the mechanism for that – a backfill pass plus an ongoing cadence, so a deregistration shows up as a flagged number on a known date instead of a surprise during an audit. That’s the mitigation story, and it’s a genuinely different conversation from the liability one above.

If you’re building the invoicing logic itself – the decision function, the country-comparison rule, what to render on the invoice – that’s the reverse-charge implementation checklist. This post is the risk case for getting a step in that checklist wrong; it isn’t a second version of the checklist.

This is general information about EU VAT rules and CJEU case law, not tax or legal advice for a specific transaction. If you’re dealing with an actual supply made against an invalid number, get a qualified adviser in the relevant jurisdiction involved before deciding how to fix it.

FAQ

Who owes the VAT if the buyer’s number turns out to be invalid?

In the reverse-charge mechanism for services, the buyer is liable under Article 196 only when the conditions actually hold. If the number was invalid, one of those conditions failed, and a tax authority can reassess the supply as a normal domestic one – with the seller assessed for the VAT that was never charged, plus interest and penalties that vary by country. This is general information, not tax advice for a specific case.

We validated at invoice time and the number was deregistered later – are we exposed?

That is a materially different fact pattern from never checking. If the check was genuine, requester-qualified, and dated to the time of supply, you have a documented basis for the treatment you applied at that moment – case law generally protects a supplier who took reasonable measures and was not party to fraud, though outcomes are fact-dependent and no single ruling guarantees a result. Keep the evidence and talk to a local adviser if this applies to a real supply you’ve already made.

Does a VIES outage mean the buyer’s VAT number is invalid?

No. VIES_UNAVAILABLE (or a national MS_UNAVAILABLE) is a transport failure, not a negative result. It tells you the check didn’t run, not that the number is bad. Treat it as ‘retry’ evidence and keep a record of the attempt.

Is a VIES screenshot enough evidence if this gets audited later?

A screenshot is self-produced and hard to date convincingly on its own. A requester-qualified VIES check that returns a consultation number is stronger, because VIES itself issues and timestamps that reference. Neither one proves the underlying supply qualified for the treatment – they prove you checked, not that the transaction was correct.

Know before you invoice, not after an audit

vatnode runs requester-qualified VIES checks – set your EU VAT number once in Settings, and every VIES check returns a definitive valid: true/false with the consultation number, source, and timestamp. So a bad number shows up before you zero-rate the invoice, not during a review two years later. Free plan, 100 requests/month.

Get a free API key · VIES API · Bulk re-validate a customer base

Booking a Shipment from an Order Pipeline Without Stalling the Rest of the Order

Iurii Rogulia — Wed, 16 Sep 2026 10:00:57 +0000

On Pikkuna, a Stripe webhook enqueues a confirmed order into a BullMQ (Redis-backed) job queue, and a worker runs through it sequentially – CRM deal, backup record, shipment, accounting entry, PDF invoice, confirmation email:

// workers/order-processor.ts
const worker = new Worker("orders", async (job) => {
  const { sessionId } = job.data;
  const session = await fetchSession(sessionId);

  await createZohoDeal(session); // CRM
  await createAirtableRecord(session); // Backup DB
  await createPostNordShipment(session); // Shipping label
  await sendToNetvisor(session); // Accounting
  const invoice = await generateInvoicePDF(session);
  await sendEmailWithInvoice(session, invoice);
});

That’s the real shape, reconstructed from the Pikkuna case study – the same worker I used for the accounting call in Wiring an Accounting System into a Payment Webhook Without Losing Money. createPostNordShipment(session) is one line in it. I don’t have PostNord’s actual booking endpoint, payload shape, auth mechanism, or error codes to hand you, and I’m not going to invent them – this article isn’t about PostNord’s API surface. It’s about the questions that line raises for any logistics-provider call sitting in a sequential order-processing worker, whichever carrier is on the other end: PostNord, DHL, a regional courier, a shipping aggregator. Three of them come up every time this pattern gets built.

Does the Booking API Answer Now, or Later?

Shipping-provider APIs split roughly into two families, and the split changes how the worker step has to be written.

Synchronous booking returns a tracking number and a label – usually a PDF or ZPL payload – in the response to the call that created the shipment. The worker step is a single await: call, get the label back, store it, move on. This is the easy case, and it’s the one the Pikkuna snippet’s single await createPostNordShipment(session) line implicitly assumes.

Asynchronous booking is different, and it’s common enough with carrier and freight APIs that it can’t be treated as an edge case. The call you make doesn’t create the shipment – it submits a booking request that gets accepted, and the carrier confirms the label and tracking number later: a webhook callback, or a status you have to poll for. In that shape, createPostNordShipment(session) can’t be one await that returns a finished shipment. It has to do two things instead – submit the booking, and record that this order has a shipment pending confirmation – because the worker function returns, moves the job on to the accounting step, and generates an invoice, all before the label exists:

// generic pattern — illustrative, not any specific carrier's API
async function bookShipment(session: CheckoutSession) {
  const bookingRef = await carrierClient.submitBooking(session);

  // No label yet. Record the booking as pending so the callback
  // or a poller has something to reconcile against later.
  await db.insert(shipmentBookings).values({
    orderId: session.id,
    bookingRef,
    status: "pending",
  });

  // The worker moves on — invoice generation doesn't wait on a label
  // that might not exist for another few minutes.
}

The invoice and confirmation email steps further down the same worker then can’t assume a tracking number exists yet. Either they render without one and a separate step (the webhook callback, or a follow-up job scheduled to poll) fills it in and re-sends, or the invoice is generated with a ‘shipping label pending’ placeholder that’s genuinely true rather than a bug. Which one is right is a product decision, not a technical one. But it has to be made deliberately: ‘assume the label exists by the time the invoice renders’ silently breaks the moment the booking API turns out to be asynchronous.

slug="api-integrations"
text="Wiring a carrier’s booking API – synchronous or webhook-confirmed – into an order pipeline that also has to keep the invoice and the accounting entry correct? Getting the sequencing and the retries right the first time is the integration work I do."
/>

Should a Slow Carrier API Stall the Customer’s Invoice?

The worker in the snippet above runs shipment booking third, before accounting and before the PDF invoice. That ordering has a consequence: if createPostNordShipment throws or hangs, the two steps after it – the accounting entry and the invoice the customer is waiting on – don’t run either, because a BullMQ job that throws partway through fails the whole job. Stripe already confirmed the charge, the webhook already returned 200, the customer paid. And now they’re waiting on their invoice because a shipping API is having a bad afternoon.

The honest answer isn’t ‘always decouple it’. It depends on which of two things is true for the business:

If the invoice is expected before the shipment ships (typical for made-to-order or B2B goods with a lead time), there’s no real coupling problem. The customer isn’t blocked on the label; they’re blocked on the invoice, and the invoice doesn’t need the tracking number to be correct. In that case the fix isn’t decoupling the shipment call at all – it’s reordering the worker so accounting and invoice generation run before shipment booking, and a failed booking retries on its own without holding up either.
If the invoice or the confirmation email is supposed to carry the tracking number – common in DTC e-commerce, which is Pikkuna’s case – the two steps are genuinely coupled by the data, not just by position in the function. Reordering doesn’t fix it; the invoice needs a label that doesn’t exist yet. Here the real fix is upstream of retry logic. Decide, as a product decision, whether the invoice can ship without a tracking number (email it now, follow up with tracking once the label exists, which is the asynchronous-booking pattern above applied by choice even when the carrier itself is synchronous) or whether the business genuinely wants every invoice blocked until a label is confirmed. Only the second choice justifies leaving createPostNordShipment in the synchronous critical path ahead of the invoice.

Either way, ‘shipment booking runs third in the function’ is not itself the design decision – it’s the default a sequential worker falls into when nobody made one. The actual decision is which downstream steps genuinely depend on the label existing, and that’s a question about the data, not about where the await happens to sit in the file.

A Booking That Succeeded but the Response Got Lost

The same failure shape that motivated the dedupe-key pattern for the accounting call applies here, for the same underlying reason: a timeout doesn’t tell you whether the carrier received the request and failed to answer, or received it, created the shipment, and the response got lost on the way back. BullMQ retries the job either way. A naive bookShipment(session) called a second time submits a second booking – a second label, a second tracking number, a second cost on the account, for one order.

The fix follows the same shape covered in Idempotency Keys: Building Retries That Don’t Double-Charge: a deterministic key derived from the order, claimed atomically before the carrier call happens, so a retry recognizes its own prior attempt instead of repeating it.

// generic pattern — illustrative, not any specific carrier's API
async function bookShipment(session: CheckoutSession) {
  const dedupeKey = `shipment:${session.id}`; // stable across retries

  const existing = await db.query.shipmentBookings.findFirst({
    where: eq(shipmentBookings.dedupeKey, dedupeKey),
  });
  if (existing?.status === "confirmed") return existing; // already booked

  // Claim the key atomically before calling the carrier. If a prior
  // attempt already claimed it and is still pending, this insert loses
  // the race — that's the signal to check status, not to book again.
  const claim = await db
    .insert(shipmentBookings)
    .values({ dedupeKey, orderId: session.id, status: "pending" })
    .onConflictDoNothing()
    .returning();

  if (claim.length === 0) {
    // Another attempt owns this key. If the carrier's API accepts an
    // idempotency key or a lookup-by-reference call, that's the honest
    // way to find out whether the earlier attempt actually landed —
    // don't just assume it did or didn't.
    return resolveExistingBooking(dedupeKey);
  }

  try {
    const { trackingNumber, labelUrl } = await carrierClient.createShipment(session);
    await db
      .update(shipmentBookings)
      .set({ status: "confirmed", trackingNumber, labelUrl })
      .where(eq(shipmentBookings.dedupeKey, dedupeKey));
  } catch (err) {
    // The carrier may have created the shipment before the timeout —
    // this record stays "pending", not "failed", until something checks.
    throw err;
  }
}

Same mechanism as the accounting pattern: the row’s claim, not the code’s control flow, decides which attempt is allowed to call the carrier. A UNIQUE constraint on dedupeKey is checked by the database at insert time, so it holds even when the retry lands on a different worker process – which, on a BullMQ job re-queued after a timeout, it may well do. In-memory dedup logic doesn’t survive that.

One thing this pattern deliberately doesn’t paper over: unlike the accounting call, a pending row here can’t always be resolved by just calling createShipment again and trusting the dedupe key alone, because the failure happened on the outbound leg to a stateful side effect at a third party – a real label may already exist, with a real cost attached, sitting in the carrier’s system under a reference this worker doesn’t have yet if it never got the response. Whether the carrier API exposes a way to look up a booking by your own reference number, or accepts its own idempotency key so a resubmission is safe by design, determines whether resolveExistingBooking above is ‘call the carrier and check’ or ‘wait for a human, because there’s no safe way to find out.’ That’s a fact about the specific carrier’s API, not something this pattern can guarantee in general. Confirm it before the first pending row shows up stuck in production, not after.

Sequencing a carrier call, an accounting entry, and an invoice generation step in the same worker function is a small amount of code that hides a real design decision: what’s allowed to fail without stalling the rest of the order. If that’s the stage your order pipeline is at, get in touch and let’s work out which steps actually need to block each other before a slow shipping API becomes a stalled invoice.

Further reading:

Wiring an Accounting System into a Payment Webhook Without Losing Money – the same Pikkuna worker, same sequential-processing trade-offs, applied to the accounting call one step further down
PostNord API and Zoho Desk Automation: Production Gotchas – PostNord’s actual endpoint behavior and error-handling quirks, for the specifics this article deliberately leaves out
Idempotency Keys: Building Retries That Don’t Double-Charge – the general dedupe-key contract this article’s shipment-booking pattern is built on
Stripe Webhooks: Idempotency, Retries, and Queue Setup – how the inbound side of this same handler deduplicates events before the job is ever enqueued
Pikkuna – E-commerce for Vinyl Curtains & PVC Products – the project this pattern is drawn from

How to Check a PDF’s Creation & Modification Dates

Iurii Rogulia — Wed, 16 Sep 2026 10:00:41 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

Every PDF carries two dates: when it was created, and when it was last saved. Open any file’s properties and you’ll find both in seconds. Both are plain text, the same kind of string as the title or the author name. Any editor that can open a PDF can rewrite them to say whatever the person editing wants.

That doesn’t make the dates useless. It makes them a claim rather than a fact. Checking a PDF’s dates properly means knowing the difference between reading them and trusting them.

Where the two dates live

The Info dictionary, a small block of metadata in the file’s trailer, can carry a CreationDate and a ModDate field. Many PDFs duplicate the same two values in an embedded XMP packet (xmp:CreateDate and xmp:ModifyDate), a second, XML-based metadata layer that Adobe tools and some other generators write alongside the Info dictionary. Both live inside the file itself, not in your filesystem. They travel with the PDF when you email it, upload it, or copy it to a new folder. For the full field-by-field breakdown of the Info dictionary, including Creator, Producer and the xref table, see PDF metadata forensics: a complete field-by-field reference. This article stays on the two date fields.

CreationDate records when the document was first generated: the moment the PDF bytes were written, not necessarily when the underlying content (a scanned page, a report’s source data) came into existence.

ModDate records when the file was last saved. Any operation that writes changes back into the file updates it: editing text, adding a digital signature, filling a form field, running the file through a compressor or format converter.

On a document generated once and never touched again, the two should match, or come close enough that the gap is meaningless.

How to check a PDF’s creation date online or offline

You don’t need any special software for a quick look.

In Adobe Acrobat Reader: open the file, then File → Properties. The Created and Modified fields are on the Description tab.

On Windows: right-click the file, choose Properties, and check the General tab.

On macOS: right-click the file, choose Get Info, and check Created and Last Modified. Finder sometimes shows filesystem timestamps rather than the values embedded in the PDF, so don’t treat what you see there as forensic-grade.

Online, without opening a desktop app: a metadata viewer that reads the file’s actual Info dictionary and XMP packet, rather than your OS’s file-manager timestamps, is more reliable. Our free PDF metadata viewer dumps every field from a file you upload — both dates, Creator, Producer, and the rest — with no account required.

Whichever method you use, you’re reading the same underlying bytes. The question is what those bytes are worth.

Why the raw values lie

CreationDate and ModDate are stored as plain-text strings in a format that looks like D:20260115093000+02'00'. There is nothing cryptographic about them. No hash, no signature, no tamper-evident seal. A text editor, a command-line metadata tool, or any PDF editor’s ‘document properties’ panel can rewrite either field to any value at all, and the file opens normally afterward with no warning that anything changed.

So a mismatch, or a suspiciously round number (‘created’ at exactly midnight, or matching today’s date on a document that claims to be years old), is not proof of fraud. A match between the two dates is not proof of an untouched file either. Someone forging a document can set both fields to whatever they want, including making them identical to hide the edit.

Read alone, the two dates tell you one honest thing and one dishonest thing. The honest thing: if they genuinely differ, something wrote to the file after it was first created. Any real save operation produces that as a byproduct. The dishonest thing: the exact values are self-reported by whatever software last touched the file, and nothing stops that software, or a person with a text editor, from writing false ones.

This isn’t a theoretical weakness. General-purpose metadata utilities exist specifically to read and rewrite these fields. That’s their entire job, and it’s a legitimate one for privacy scrubbing before you share a file. The same capability that lets you strip your name from a PDF before sending it to a stranger lets someone backdate a document by five years with one command. The field doesn’t know, or care, which use case it’s serving.

What a plain glance at the dates can’t tell you

Two documents can carry identical, perfectly plausible CreationDate and ModDate values and still be nothing alike underneath. A bank statement generated once by an institutional system and a bank statement built from a template, with the balance changed and the dates manually reset to look consistent, can present the exact same two numbers in Properties. The dates report what the last piece of software claimed. They carry no information about whether that claim is true.

This is the gap between ‘checking a PDF’s dates’ and ‘verifying a PDF’s dates.’ Checking is reading the two fields. Verifying means asking whether the rest of the file’s structure — how many times it was actually saved, what software produced it, whether a signature or format conversion accounts for any gap — is consistent with the story the dates are telling. A forger who resets both fields to match still leaves the save history, the producer fingerprint, and the cross-reference structure largely as they found them. Rewriting those convincingly takes more than a metadata editor.

Gaps that are normal, and gaps that aren’t

Not every difference between CreationDate and ModDate means someone tampered with the document. Several ordinary workflows produce a real, legitimate gap:

Signing in the same sitting. Open a document, sign it, save it. That whole sequence can land within a few seconds of CreationDate, because applying a signature is itself a save operation.
PDF/A conversion. Archival-format conversion rewrites the file’s structure even when the visible content doesn’t change, which updates ModDate. The file genuinely was re-saved, and the conversion is a real reason for it.
Batch or scheduled report generation. Some generation engines set CreationDate when a document template or job is defined and only stamp ModDate when the specific instance is rendered and saved. The gap reflects two pipeline stages, not anyone opening and editing content afterward.

A benign reason for a gap explains it; it doesn’t erase it. If a file was reopened and re-saved days or weeks after it was first created, for a signature or a re-export, that is a real event in the file’s history, and a structural check surfaces it as one. Whether the event matters for your workflow is your judgment call. The tool’s job is only to report that the write happened.

What a structural check adds

HTPBE’s detection algorithm doesn’t stop at comparing two numbers. A few things it evaluates that a manual glance at Properties can’t:

Why ordinary generation doesn’t trip this. A generator may write CreationDate when a document workflow starts and ModDate when the render finishes. That is normal generation behavior, and the date analysis is built so it isn’t reported as a modification.

Cross-checking the two metadata layers against each other. When a PDF carries both an Info-dictionary date and an XMP date for the same event, they should normally describe the same moment. A disagreement usually means one layer was edited independently of the other — a partial edit that a manual check of one field misses entirely. That produces HTPBE_TIMESTAMP_LAYERS_DISAGREE.

Catching physically impossible values. A creation date decades before the PDF format existed, or a date meaningfully in the future, isn’t a normal software quirk. No generator legitimately produces it. That’s HTPBE_IMPOSSIBLE_TIMESTAMP.

HTPBE still checks the file’s broader structure first — how many times it was actually saved, what software last touched it — because a verdict rests on the whole file, not a single field. A full list of what each marker checks for is in the forensic checks catalog.

Reading a structural result

Submitting a PDF to the HTPBE API returns both raw date fields and the algorithm’s read on them as structured JSON. An abridged slice of the response, showing only the date-relevant fields:

{
  "id": "506a6b1b-1360-48a2-b389-abb346f85d04",
  "status": "modified",
  "modification_confidence": "certain",
  "modification_markers": ["HTPBE_DATES_DISAGREE"],
  "creation_date": 1704110400,
  "modification_date": 1707840000,
  "creator": "Adobe Acrobat Pro DC",
  "producer": "Adobe PDF Library 15.0",
  "usage_caution": {
    "safe_for_automated_adverse_decision": false,
    "recommended_action": "route_to_human_review",
    "message": "Structural evidence of post-creation modification was found. Route this document to a human reviewer before any decision — do not use this verdict as the sole basis for an automatic adverse decision against a person."
  }
}

creation_date and modification_date are Unix timestamps in seconds, here roughly 43 days apart – the file was written to long after it was created. modification_confidence: "certain" reflects that this is consistent with a genuine post-creation write. usage_caution is present on every response as a reminder that a file-level finding should route to review, not drive an automatic decision about the person who submitted it. The full response schema, including every field this endpoint returns, is documented at /api.

Common questions

Can a PDF’s creation date be changed after the fact? Yes, trivially, with any of several free metadata-editing utilities or a hex editor. That’s why the date fields alone are a claim rather than evidence.

Does printing a PDF or converting it change the dates? Printing to a physical printer doesn’t touch the file’s metadata. Converting a file — re-saving from one format to another, running it through an optimizer — almost always updates ModDate, because the conversion tool writes a new file. The file you’re looking at isn’t byte-for-byte the one that was first generated, and a structural check reports that write either way. ‘Print to PDF’ is a separate case: it produces a file with no PDF-editing history to find at all, and the honest verdict for that is inconclusive, not a clean bill of health.

Why does my PDF show a creation date in the future? A timestamp slightly ahead of the current time is usually clock drift on the machine that generated it. Hours or days out is a different matter. We cover this specific case in more depth in why does my PDF show a future creation date.

Do matching dates prove a PDF wasn’t edited? No. Some generators set both fields to the same value on export regardless of what happened before, and anyone editing a file with a metadata tool can reset both to match on purpose. Matching dates are consistent with an untouched file; they aren’t proof of one.

I need the number of times a file was actually saved, not just whether the dates differ. That’s a different question, answered by the file’s revision chain rather than its date fields. See how to view a PDF’s edit history for how to read that separately.

I want the full checklist, not just the date fields. Has this PDF been edited? Five ways to check covers metadata alongside visual inspection, signatures, and automated tools. This article stays on the date fields because they’re the check most guides get wrong.

A short checklist

For a single file, right now:

Open the document properties (Acrobat, OS file properties, or a metadata viewer) and note both dates.
If they match exactly, that’s consistent with an untouched file, not proof of one.
If they differ, look for a plausible explanation — a same-sitting signature, a format conversion, a template-vs-instance report pipeline — before assuming the worst. The explanation doesn’t erase the write.
For anything that needs a verdict rather than a guess — a loan application, a signed contract, a submitted invoice — run a structural check. Plausible-looking dates on a forged document prove nothing about the rest of the file; a structural check evaluates them alongside everything else the file’s bytes reveal.

None of that scales to a queue of applications, contracts, or invoices, and a reviewer scanning Properties by hand won’t catch a date pair a forger reset to look clean. That’s a job for an API call. The HTPBE API returns creation_date, modification_date, and the full modification_markers array on every request. Register for 5 free checks and a free test API key, so you can run the endpoint against synthetic documents before pointing anything at production files. The entry plan runs 30 checks a month from there, and current pricing covers the higher tiers.

Build Against the VAT API Without Burning Quota

Iurii Rogulia — Wed, 16 Sep 2026 09:00:43 +0000

Originally published at vatnode.dev. The version on vatnode.dev is the canonical source — refer to it for the latest content.

Build Against the VAT API Without Burning Quota

Every vatnode account gets a test API key automatically, prefixed vat_test_ instead of vat_live_. Point it at a reserved XX VAT number and you get back a fixture response – no VIES call, no database write, no quota spent. That’s the whole mechanism. The rest of this post is what you can actually build with it.

The API resolves the environment from the key itself, not from anything in the request body or URL. Send a vat_test_ key with any GET /v1/vat/:vatId request and you’re in test mode for that call, full stop.

What a test key actually skips

When the API sees a vat_test_ key, it short-circuits before doing any of the work a live request does:

Format validation is skipped, except one check – the VAT ID has to start with XX.
No call to VIES or a national fallback is made.
Nothing is written to your validation history (vat_checks).
Your monthly quota counter is not incremented.

Be precise about that last point – ‘no effect on your data’ oversells it slightly. Test calls never count against your monthly quota and are never written to your validation history. The only record kept is a one-time timestamp of your first test call, used internally for onboarding – it doesn’t reflect the specific VAT number or result you tested. You won’t see individual test checks anywhere in your dashboard, and you can hammer the endpoint as hard as you like.

Full reference, including the response schema, lives in Test Mode. If you haven’t looked at how vatnode structures the seven documented error codes, Handling VIES Errors in Code is the companion piece – the fixtures below are the fastest way to actually trigger those codes without waiting for a real outage.

The XX fixture numbers

Test mode only accepts VAT numbers starting with XX – a prefix reserved specifically because it can never collide with a real member-state format. Five specific numbers map to distinct scenarios; everything else in the XX* space falls back to a default invalid result.

VAT number	HTTP	Result	What it’s for
`XX0000001`	200	`valid: true`, full company name + address	Happy path
`XX0000002`	200	`valid: true`, `companyName`/`companyAddress` null	Valid VAT where VIES returns no company details (mirrors Germany)
`XX0000003`	200	`valid: false`	Not found / deregistered
`XX0000004`	503 `VIES_UNAVAILABLE`	—	VIES member-state node down
`XX0000005`	502 `VIES_ERROR`	—	Unexpected upstream protocol fault
any other `XX*`	200	`valid: false`	Default fallback
non-`XX` number	400 `INVALID_FORMAT`	—	Test mode rejects it – message tells you to use `XX` numbers

A word on how close this is to a live response: the test response uses the same field names and types as a live response for every documented field. It won’t be byte-for-byte identical – checkId, verifiedAt, and countryVat.countryVatUpdatedAt are generated fresh on each call, the same way they are live. What’s fixed per fixture is the verdict and the company fields, so you get deterministic verdicts to assert against without deterministic timestamps to mock around.

One more detail that trips people up: fixture responses report source: "VIES" so your source-handling logic gets exercised the same way it would on a live VIES answer – but no call to VIES is made. Treat it as a label for your parser, not as evidence a lookup happened.

Happy path

curl https://api.vatnode.dev/v1/vat/XX0000001 \
  -H "Authorization: Bearer vat_test_your_test_key"

{
  "valid": true,
  "vatId": "XX0000001",
  "countryCode": "XX",
  "countryName": "Test Country",
  "companyName": "Test Company Ltd",
  "companyAddress": "1 Test Street, Test City, TC1 0AA",
  "consultationNumber": null,
  "verifiedAt": "2026-09-09T10:00:00.000Z",
  "checkId": "019d2a89-a5d9-7b97-b710-57b84604de2b",
  "source": "VIES"
}

consultationNumber is always null in test mode, on every fixture, regardless of what requester VAT number is set on your account. It’s only ever populated on a live VIES consultation.

And the same call in TypeScript:

async function checkVat(vatId: string, apiKey: string) {
  const res = await fetch(`https://api.vatnode.dev/v1/vat/${vatId}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  })

  if (!res.ok) {
    const { error } = await res.json()
    throw new Error(`${error.code}: ${error.message}`)
  }

  return res.json()
}

const result = await checkVat('XX0000001', 'vat_test_your_test_key')
console.log(result.valid, result.companyName)

Wiring the fixtures into a test suite

The five scenarios map cleanly onto assertions. This is the pattern to lift into your own integration tests – no mocking, no fixtures of your own to maintain, no live key required in CI:

const TEST_KEY = process.env.VATNODE_TEST_KEY! // vat_test_...

async function checkVat(vatId: string) {
  const res = await fetch(`https://api.vatnode.dev/v1/vat/${vatId}`, {
    headers: { Authorization: `Bearer ${TEST_KEY}` },
  })
  return { status: res.status, body: await res.json() }
}

test('valid VAT with full company details', async () => {
  const { status, body } = await checkVat('XX0000001')
  expect(status).toBe(200)
  expect(body.valid).toBe(true)
  expect(body.companyName).toBe('Test Company Ltd')
})

test('valid VAT with no company details on file', async () => {
  const { status, body } = await checkVat('XX0000002')
  expect(status).toBe(200)
  expect(body.valid).toBe(true)
  expect(body.companyName).toBeNull()
})

test('deregistered VAT number', async () => {
  const { status, body } = await checkVat('XX0000003')
  expect(status).toBe(200)
  expect(body.valid).toBe(false)
})

test('VIES unavailable degrades, does not fail closed', async () => {
  const { status, body } = await checkVat('XX0000004')
  expect(status).toBe(503)
  expect(body.error.code).toBe('VIES_UNAVAILABLE')
})

test('VIES protocol error', async () => {
  const { status, body } = await checkVat('XX0000005')
  expect(status).toBe(502)
  expect(body.error.code).toBe('VIES_ERROR')
})

test('non-XX number rejected in test mode', async () => {
  const { status, body } = await checkVat('DE143454214')
  expect(status).toBe(400)
  expect(body.error.code).toBe('INVALID_FORMAT')
})

Run that suite against XX0000004 and XX0000005 and you’ve exercised the exact retry/degrade branches from Handling VIES Errors in Code – 503 and 502 – without depending on VIES actually being down when your CI runs. The full error vocabulary, including the codes test mode can’t reach (RATE_LIMITED, INVALID_REQUESTER, UPSTREAM_TIMEOUT, INTERNAL_ERROR), is in Errors.

The bulk endpoint runs the same fixtures through a real job

If you’re validating in batches, Bulk VAT Validation accepts test keys too, and the same XX* fixtures apply per position. A test job is a real job – same jobId, same submit → poll → page contract a live job uses, just paid for in fixtures instead of quota. You can build and test your entire polling and pagination consumer, including per-position error branching, before a live VAT ID ever touches the endpoint.

Submitting is the same as with a live key – 202, nothing validated during the request:

curl -X POST https://api.vatnode.dev/v1/vat/bulk \
  -H "Authorization: Bearer vat_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{"vatIds": ["XX0000001", "XX0000004", "DE12345"]}'

{
  "jobId": "0f8b1d64-4a1e-4a5e-9f4a-2b1c8d3e5f60",
  "status": "queued",
  "totalItems": 3,
  "duplicatesDropped": 0,
  "createdAt": "2026-09-09T10:00:00.000Z"
}

A test job runs every position at once rather than at the throttled concurrency a live job uses, so by the time your first GET lands it’s usually already finished. Page through the results the same way you would for a live job:

curl "https://api.vatnode.dev/v1/vat/bulk/0f8b1d64-4a1e-4a5e-9f4a-2b1c8d3e5f60/results?page=1&limit=100" \
  -H "Authorization: Bearer vat_test_your_test_key"

{
  "items": [
    {
      "position": 0,
      "vatId": "XX0000001",
      "status": "done",
      "valid": true,
      "source": "VIES",
      "consultationNumber": null,
      "checkId": null,
      "error": null,
      "processedAt": "2026-09-09T10:00:00.400Z"
    },
    {
      "position": 1,
      "vatId": "XX0000004",
      "status": "done",
      "valid": null,
      "source": null,
      "consultationNumber": null,
      "checkId": null,
      "error": {
        "code": "VIES_UNAVAILABLE",
        "message": "VIES service is temporarily unavailable"
      },
      "processedAt": "2026-09-09T10:00:00.410Z"
    },
    {
      "position": 2,
      "vatId": "DE12345",
      "status": "done",
      "valid": null,
      "source": null,
      "consultationNumber": null,
      "checkId": null,
      "error": {
        "code": "INVALID_FORMAT",
        "message": "Test mode only accepts XX VAT numbers (e.g. XX0000001). Use your live key for real VAT IDs."
      },
      "processedAt": "2026-09-09T10:00:00.415Z"
    }
  ],
  "total": 3,
  "page": 1,
  "pages": 1
}

XX0000001 comes back with checkId: null – same as every test-mode result, single or bulk: no quota spent, no VIES call, no stored check.

XX0000004 and XX0000005 reproduce the same VIES_UNAVAILABLE and VIES_ERROR codes the single endpoint returns as an HTTP status, except a bulk position doesn’t carry an HTTP status of its own at all. The job’s own calls (submit, poll, page) stay in the 200s regardless of what happened to any individual position; the outcome lives entirely in that position’s error object.

A non-XX entry like DE12345 becomes an accepted position carrying INVALID_FORMAT in error, not a 400 that would reject the whole submission.

Duplicate vatIds in the same batch are deduplicated on intake, test key or live – send XX0000001 three times and it becomes one position, counted in duplicatesDropped on the 202.

The position shape is leaner than the single endpoint here too – no companyName or companyAddress. Follow up with GET /v1/vat/:vatId if you need company details for a specific item.

Where test keys don’t work

Test mode covers the VAT-check endpoints – single and bulk – and nothing else. Subscriptions and webhooks reject a vat_test_ key with 403 TEST_KEY_NOT_ALLOWED, because those act on real VAT numbers and deliver real HTTP callbacks to your endpoint. There’s no sandbox version of ‘revalidate this customer monthly’ or ‘POST a signed payload to your server’ – both are live-key-only. Build and test the validation call against fixtures; switch to a vat_live_ key before you wire up monitoring or webhook delivery.

FAQ

Does using a vatnode test key ever hit the real VIES service?

No. A request authenticated with a vat_test_ key short-circuits before any network call – VIES and every national fallback are skipped entirely. The response comes from a hardcoded fixture, not a lookup.

What VAT numbers work in test mode, and why do they have to start with XX?

Only numbers starting with XX. XX is a reserved prefix that can never match a real member-state VAT number, so it can’t be confused with production data. Five specific XX numbers (XX0000001 through XX0000005) trigger distinct scenarios; any other XX* number returns the default invalid result. A non-XX number with a test key returns 400 INVALID_FORMAT on the single endpoint; in a bulk job, the same rejection is a per-position INVALID_FORMAT error on an otherwise-accepted job, not a 400 for the whole submission.

Will test-mode requests count against my monthly quota or plan limits?

No. Test calls never count against your monthly quota and are never written to your validation history. The only record kept is a one-time timestamp of your first test call, used internally for onboarding – it doesn’t reflect the specific VAT number or result you tested.

Can I get a consultationNumber back from a test-mode check?

No. consultationNumber is always null in test mode, on every fixture, regardless of whether your account has a requester VAT number configured. It’s only ever populated on a live VIES consultation.

Next step

Every account already has a test key sitting in your dashboard’s API Keys section – you don’t need to request one or wait for approval. Point your integration at the VAT API or the VIES API reference for the full field list, build against the XX fixtures above, and swap in a live key once your error handling passes.

Get a test key and a live key from the same account

Sign up and vatnode creates your vat_test_ key automatically, ready to hit the fixtures above. The full API reference covers what changes when you switch to a live key.

Get your free API key

Custom Software vs Off-the-Shelf: When to Build Your Own

Iurii Rogulia — Mon, 14 Sep 2026 10:01:01 +0000

Most businesses that ask me whether they should build custom software should not build custom software. They should use Shopify, or HubSpot, or whatever off-the-shelf platform fits their category, and spend the money on something else.

I say this as someone whose actual work is building custom software. It’s still true.

Off-the-Shelf Is the Right Default

A platform like Shopify represents thousands of engineering years you don’t have to pay for. Payments, tax, hosting, security patches, checkout that converts, an app ecosystem for the common cases – all of it maintained by someone else, forever, for a monthly fee that’s a rounding error compared to a development budget.

When you build custom, you own all of that. Not just the first version – the maintenance, the security updates, the edge cases you didn’t think of, the thing that breaks at the worst possible time. Custom software is not a purchase. It’s a commitment.

So the honest default is: start off-the-shelf. If a platform can run your business, let it. The businesses that jump to custom too early usually end up with something more expensive and more fragile than the thing they were trying to escape, and they still have to hire someone to keep it alive.

The question is not ‘is custom better.’ Custom is not better. The question is whether the platform is standing between you and the way your business actually works – and whether that’s costing you real money.

The Signal That Actually Matters

There’s one signal that separates ‘you’re using the platform wrong’ from ‘you’ve outgrown the platform’: the platform blocks your business logic, not your styling.

Wanting a different colour scheme is not outgrowing the platform. Wanting a slightly different checkout layout is not outgrowing the platform. Those are configuration problems, and a platform that can’t handle them is rare.

You’ve outgrown the platform when the thing it can’t do is the thing your business is actually built on. When the way you make money doesn’t fit the shape the platform expects – and no amount of apps, plugins, or paid tiers closes the gap.

Here’s what that looks like in practice.

When the Platform Blocks the Business

A Finnish manufacturer I worked with, Pikkuna, sells made-to-order vinyl curtains and PVC products. Not fixed SKUs – products where the customer chooses dimensions, material, and mounting options, and the price recalculates from those choices in real time.

Shopify was ruled out early, and not because anyone disliked it. It could not handle the product configurators the business was built on. A store that sells ‘product A for €40’ is exactly what off-the-shelf platforms are designed for. A store that sells ‘your dimensions, your material, priced live as you choose’ is not a styling problem. It’s the core of the business, and it fell outside what the platform could do.

That alone might have been survivable. The second problem was not. Every order was being processed by hand: confirm the payment, create the deal in the CRM, log the accounting entry, book the shipment, generate a PDF invoice, email it to the customer. Thirty minutes of manual work, spread across four separate tools, repeated for every single order.

At a dozen orders a week, a person can do that. The business was about to expand across Europe – 32 countries, a different VAT rate for every market. The manual flow that worked locally would not survive that. It wasn’t a cost you could absorb; it was a wall.

So we built custom. The manual order flow became a single automated pipeline: payment confirmed, and the CRM, accounting, shipping, invoice, and customer email all happen without anyone touching them. Thirty minutes became under two. The configurators the platform couldn’t do became the front door of the store.

There’s a part the ‘custom is a last resort’ framing gets wrong, though. Once you’re on the right side of that line, custom stops being a compromise you settle for and becomes a lever. Pikkuna’s store runs exactly the way the business runs – not the way a platform assumed it should. The configurator Shopify couldn’t model is the thing customers come for. The order pipeline nobody touches is a cost that stays flat while volume climbs. A competitor running the same business off-the-shelf is capped at whatever that platform allows; Pikkuna isn’t. That’s not damage control – it’s an edge you can only get by building the software around the business instead of bending the business around the software.

That’s the shape of a real ‘build custom’ decision. Not ‘we wanted more control.’ Specific business logic – real configurators, per-market VAT, an order flow spanning four tools – that the platform structurally could not do, on a scale where doing it by hand would have broken the business.

slug="e-commerce"
text="I build custom e-commerce and business platforms for companies that have hit a real wall with off-the-shelf – configurators, multi-market VAT, automated order flows across CRM, accounting and shipping. If you’re not there yet, I’ll tell you that too."
/>

The Signals, Made Concrete

You don’t need a Pikkuna-scale expansion to justify custom. You need at least one of these to be true, and true about your core business, not your wishlist:

The platform can’t model what you sell. Configurable products, real-time custom pricing, quotes instead of fixed prices, bundles the app store can’t express. If the way you price and package is fundamentally not ‘product × quantity,’ you’re fighting the platform.
Your business logic spans tools it can’t cross. The moment an order touches your CRM, your accounting system, your shipping provider, and your invoicing – and the platform expects each of those to be a separate manual step – you’re paying people to be the integration. Automating a flow like that is often where custom pays for itself first.
Compliance is a first-class part of the sale. Per-market VAT, VIES validation for B2B buyers, reverse-charge invoicing, region-specific payment methods. On the pi-pi.ee B2B platform, a German buyer expects their VAT number validated against the EU registry and the correct reverse-charge notation on the invoice – automatically. Platforms treat that as an edge case. For some businesses it’s the whole transaction.
You’re paying enterprise pricing to work around the platform. Shopify Plus and its equivalents can do a lot, at enterprise pricing that runs from roughly €25,000 a year well into six figures at scale – plus bespoke development for everything they still can’t do natively. When the platform tier is expensive and you’re still building around it, the ‘cheaper’ option stopped being cheaper.
The workaround has become the process. A spreadsheet three people edit at once. A manual copy-paste step nobody’s allowed to skip. A ‘temporary’ fix from two years ago that’s now load-bearing. If nobody actually owns the glue holding your systems together, that’s a risk, not a system.

If none of these describe you, you probably don’t need custom software. That’s not a disappointing answer. It’s a saved budget.

The Honest Version of This Decision

There’s a version of this conversation where a developer tells you that yes, you absolutely need custom software, and quotes you for it. Of course they do – that’s what they sell.

The version I try to have is different. Sometimes the right answer is ‘keep using Shopify, you’re not using half of what you already pay for.’ Sometimes it’s ‘you need one integration, not a rebuild.’ And sometimes it’s ‘the platform genuinely can’t do the thing your business runs on, and every month you spend working around it is money and risk you’re absorbing quietly.’

Telling those three situations apart is the actual job. It’s closer to what an IT partner does than what a developer does – asking what your business actually needs before anyone quotes a build. A build that solves a configuration problem is worse than the configuration you started with. A platform that can’t run your business is a ceiling you’ll keep hitting until you deal with it.

Custom software development is worth it exactly when the platform is the thing in your way – and not one day before.

If you’re weighing a platform against a custom build and you’re not sure which side of that line you’re on, let’s figure that out before you commit to either.

How to View a PDF's Edit History: Reading the Timeline

Iurii Rogulia — Mon, 14 Sep 2026 10:00:44 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

‘Was this PDF edited?’ has a yes/no answer. ‘What is this PDF’s edit history?’ is a different, more useful question – it asks for a timeline: how many times was the file saved after it was created, and what changed in each pass. Most guides answer the first question. This one answers the second.

You don’t need forensic software to get a partial answer, and you don’t need to guess either. A PDF’s modification history is a real, structural thing – not a log file, but a chain of save events the format itself is built to preserve. This guide covers where that history lives, how to read it by hand, and how to read it properly with a structural analysis tool when a glance at two dates isn’t enough.

What ‘edit history’ means for a PDF

A PDF isn’t one solid block of text the way a .docx file behaves in casual use. It’s a set of numbered objects – pages, fonts, images, the metadata dictionary – written into the file, plus an index that tells a PDF reader where to find each one. When most PDF software saves changes to an existing file, it doesn’t rewrite that index from scratch. It appends: new objects go on the end of the file, followed by a new copy of the index, followed by a pointer back to the previous index. Save the file three times and you get three of these index sections chained together, each one pointing to the one before it.

That chain is the closest thing a PDF has to a built-in edit history. It’s not a list of ‘changed line 4’ the way source-control history is – but it does tell you, unambiguously, how many times the file was saved after it was first created, and roughly which objects changed in each session. We cover the byte-level mechanics of that chain – what the sections actually look like, how the pointers work – in PDF xref table forensics. This article is about reading the resulting timeline, not building it from scratch.

Two things worth being precise about before going further:

‘Edit’ here means ‘saved a change to the file after it existed.’ That includes malicious edits, but also routine ones – adding a signature, filling a form field, running the file through a compressor.
The timeline tells you that something happened and roughly what object changed, not why. Reading intent – was this a legitimate correction or a forged balance – takes context the file itself doesn’t carry.

The quick manual check: dates and metadata

Every PDF stores a CreationDate and a ModDate in its Info dictionary (and often duplicates in embedded XMP metadata). Comparing them is the fastest – and weakest – way to spot activity:

Open the file in Adobe Acrobat Reader and check File → Properties, or right-click the file in Finder/Explorer and check its properties.
If Created and Modified match, the file has probably only been through one save session.
If they differ, something happened after creation – but that’s all a date comparison tells you. It doesn’t say how many times, in what order, or which parts of the document.

Two problems make this check unreliable on its own. First, some PDF generators set both dates identically even after real edits, so a match isn’t proof of an unedited file. Second, and more relevant to a genuine history: a single modification date collapses every save session into one number. A file saved five times after creation and a file saved once look identical if you’re only reading the date field. If you want the actual count of sessions – the timeline itself – the date fields are the wrong place to look. The structural chain described below is.

Metadata gives one more clue worth checking while you’re in there: the Creator and Producer fields. Creator names the authoring application; Producer names whatever software last wrote the PDF bytes. A mismatch – say, Creator: Microsoft Word next to Producer: iLovePDF – is consistent with the file having passed through a second tool after leaving Word. It’s a hint, not a timeline entry: it tells you a tool touched the file, not when or how many times. Our free PDF metadata viewer dumps every field from a file without an account, if you want to see this for yourself on a specific document.

Where the real timeline lives: the revision chain

The structural chain described above – the append-only index sections – is where an actual count of save sessions lives. You can approximate reading it yourself with a text editor on a small file: open the PDF in a plain-text or hex editor, search for the literal string %%EOF. Each occurrence marks the end of one saved revision. One %%EOF means one session – the file as originally exported, untouched since. Two or three means the file was saved again, and again, after that.

This works in principle but gets impractical fast. Larger PDFs, PDFs using the newer binary xref-stream format (common from PDF 1.5 onward), and PDFs where a viewer displays the file differently than its raw bytes are all real complications a manual %%EOF count runs into. It also doesn’t tell you which objects changed in each session – did session two touch the invoice total, or just add a digital signature? Answering that requires actually parsing the chain, not eyeballing markers in a text editor.

This is the part a structural analysis tool is built for: walking the chain, counting the sessions, and reporting which objects were touched in each one – turning ‘the file has three %%EOF markers’ into ‘the file was created, then re-saved once with only the Info dictionary changed, then re-saved again with page content changed.’

Reading the timeline from an API response

Submitting a PDF to the HTPBE API returns the revision chain as structured data instead of raw bytes to interpret by hand. A relevant slice of the response:

{
  "id": "ck_7b3e1a09-...",
  "status": "modified",
  "modification_confidence": "high",
  "modification_markers": ["HTPBE_MULTIPLE_REVISION_LAYERS"],
  "xref_count": 3,
  "has_incremental_updates": true,
  "update_chain_length": 2,
  "creator": "Microsoft Word",
  "producer": "iLovePDF",
  "creation_date": 1704067200,
  "modification_date": 1709251200
}

Read as a timeline, this says: the file has been through three save sessions (xref_count: 3 – the original export plus two later saves, so update_chain_length: 2). has_incremental_updates: true confirms at least one of those later saves happened. The creator/producer mismatch – authored in Word, last touched by iLovePDF – tells you the most recent session was written by a different tool than the one that created the file. It doesn’t by itself tell you whether both later sessions came from iLovePDF or from two different tools; producer only records whoever wrote the file last, not a log of every tool that touched it along the way.

modification_markers is where the tool names why it reached a verdict, not just what the chain looks like – HTPBE_MULTIPLE_REVISION_LAYERS here means the multi-session chain was the signal that drove the modified status. The full list of what each marker means is in the forensic checks catalog; the xref table forensics article walks through how the verdict engine weighs xref data against the other signals it checks.

What ‘which session changed what’ actually gives you

A revision count on its own – ‘this file was saved three times’ – is a coarse signal. A signed contract that picked up two routine re-saves (a signature, a form-field fill) and a bank statement that was opened once in an editor to change a balance can both show update_chain_length: 2. The count alone doesn’t separate them.

What does is knowing which object changed in which session. Each save in the chain only touches the objects that were actually edited – the rest of the file’s objects stay untouched, referenced from earlier in the chain. A session that only rewrote the Info dictionary (metadata) reads very differently from a session that rewrote a page’s content stream (the visible text and layout). The first is consistent with something like re-saving after a metadata cleanup; the second is consistent with the document’s visible content actually changing. This is the level of detail a manual %%EOF count can’t reach – counting markers tells you how many sessions happened, not what happened in each one – and it’s the reason structural analysis reads the chain object-by-object rather than just counting its sections.

Fetching this for a file you have a URL for:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-storage.example.com/documents/contract.pdf"}'

# { "id": "ck_7b3e1a09-..." }

curl https://api.htpbe.tech/v1/result/ck_7b3e1a09-... \
  -H "Authorization: Bearer YOUR_API_KEY"

The second call returns the full object above, including update_chain_length and modification_markers. Building a document intake pipeline that needs to log a revision count for every file that comes through – loan applications, signed contracts, submitted invoices – is a matter of persisting those two fields alongside whatever else you already store per document.

When the timeline isn’t there to read

A revision chain only exists if the file has one to show. Two situations erase it entirely, and it’s worth knowing both before you treat an empty timeline as proof of an untouched file.

The document was created in consumer software. Word, Google Docs, a phone’s ‘print to PDF,’ and similar tools produce a single, clean revision chain even for a file assembled specifically to deceive – because no PDF editing ever happened. Someone who changes a number directly in the source document before exporting to PDF leaves no trace in the chain; the export itself is the only save event that exists. This is exactly the case HTPBE’s inconclusive verdict is for: not a failure to analyze the file, but an honest statement that the file’s origin makes structural history unavailable. It’s covered in more depth in what inconclusive means.

The file was rebuilt rather than incrementally saved. Tools like Ghostscript, qpdf, and most ‘flatten’ or ‘optimize’ operations don’t append to the existing chain – they output a fresh, single-revision file from scratch. If a document was edited and then run through one of these tools before being sent to you, the multi-session history that edit created is gone. The modification happened; the timeline evidence of it did not survive the rebuild.

Neither case means a tool is broken or a check failed. They mean the timeline itself doesn’t carry the answer for that particular file, and a verdict built on top of missing structural evidence needs to say so rather than guess.

A short checklist

For a single file, right now:

Check the Created/Modified dates in the document properties – a mismatch means something happened, nothing more specific.
Pull the Creator/Producer metadata – a mismatch between the two is consistent with the file having passed through a second tool.
If you need the actual session count rather than a date guess, run the file through a structural analysis tool that reads the revision chain directly, rather than counting %%EOF markers by hand.
Treat inconclusive results as ‘this file’s origin doesn’t preserve a structural history,’ not as an error.

For checking PDFs in volume – a loan queue, an AP inbox, signed-contract intake – steps 1–2 don’t scale and step 3 needs to happen automatically. The HTPBE API returns xref_count, update_chain_length, and the full modification_markers array on every analysis call, and the entry plan covers 30 checks a month; see current pricing for the higher tiers. You can pull your first result with a free test API key against synthetic documents before pointing it at production files.

Validate VAT Numbers at Checkout, Not Just at Signup

Iurii Rogulia — Mon, 14 Sep 2026 09:00:47 +0000

Originally published at vatnode.dev. The version on vatnode.dev is the canonical source — refer to it for the latest content.

Validate VAT Numbers at Checkout, Not Just at Signup

A VAT ID field at checkout has one job: help you decide, before payment, whether this specific order should carry VAT or not. That’s a different problem from validating a VAT ID at signup – signup is about a stored customer attribute checked once, off the critical path of account creation. Checkout is about a single order total, computed live, often for a guest who has no account and never will – the cart-level eligibility decision this post is about.

The scope is EU-27 plus XI (Northern Ireland – goods only via VIES), intra-Community B2B only – no OSS, no distance-selling thresholds, no VAT calculation or filing.

What the VAT ID field at checkout is actually deciding

A VAT ID entered at checkout is evidence for one of two different legal questions, depending on what’s in the cart:

Goods. Since the 2020 Quick Fixes, a valid buyer VAT ID – plus a correct entry on your EC Sales List – is a substantive condition for zero-rating an intra-Community supply of goods (Council Directive (EU) 2018/1910, amending Art 138 of the VAT Directive). This is exemption, not reverse charge – the terms aren’t interchangeable. Art 138(1a) is rebuttable (‘unless the supplier can duly justify his shortcoming’), so a missing or invalid VAT ID isn’t necessarily fatal to the treatment, but it removes your cleanest path to it. And a valid VAT ID alone never finishes the job for goods: the items still have to physically leave the dispatch member state, with transport evidence – the rebuttable presumption mechanism is Art 45a of Implementing Regulation 282/2011, inserted by Reg (EU) 2018/1912.
Services. This is the actual reverse charge: the place of supply moves to the customer (Art 44) and the customer self-accounts for the VAT (Art 196). Your usable basis for treating the customer as a taxable person is Implementing Regulation (EU) 282/2011 Art 18(1)(a): the customer communicated a VAT ID, and you obtained confirmation of its validity and its associated name and address. VIES doesn’t return a name and address for German or Spanish numbers, so full Art 18(1)(a) evidence for those two needs a source beyond VIES.

Neither rule says ‘run a VIES check.’ The statute requires the customer to hold and communicate a valid VAT ID; VIES is the evidentiary tool that shows you obtained confirmation in good faith (Reg 904/2010 Art 31). That distinction matters for how you build the checkout flow: the check is evidence-gathering, not a legal gate by itself, so it shouldn’t block the transaction it’s supposed to support. Background on the two regimes side by side is in VAT reverse charge and the do-I-charge-VAT reference.

Why checkout is a harder problem than signup

At signup, a pending VAT check just means the account is created and the field says ‘verifying.’ At checkout, the VAT ID can change the number on the payment page the customer is about to authorize – so the wrong instinct is stronger: block payment until the check comes back clean.

Don’t. VIES has no SLA. An outage code – VIES_UNAVAILABLE, UPSTREAM_TIMEOUT, VIES_ERROR – means ‘VIES didn’t answer, try again,’ not ‘not registered.’ A RATE_LIMITED or INVALID_REQUESTER means your own quota or requester config is the problem: still not a verdict on the buyer, and not something a retry fixes. None of them is a reason to block the buy button – doing so turns a national tax authority’s maintenance window, or your own misconfiguration, into your abandoned-cart number. The only answer that means ‘not currently VAT-registered’ is a check that completed with valid: false. A check that hasn’t completed yet is not that answer.

The fix is the same shape as at signup, applied to the order total instead of the account: format-check the field inline, run the real check server-side without blocking payment, and gate only the specific decision – zero-rate this order or not – on a completed answer.

Guest checkout: the VAT ID is a one-time order field, not a customer record

Most e-commerce checkout has no signup pattern to reuse in the first place: the buyer is a guest, there’s no account row to attach a ‘pending’ flag to, and the VAT ID exists only for the duration of this order. Design around that:

Store the check result on the order, not on a customer entity that may not exist tomorrow.
Don’t defer the decision to ‘next time they log in’ – there is no next time for a guest.
The order is also the audit unit later, so the evidence (the response fields below) needs to live wherever the order record lives, immutably, once the order is placed.

A checkout handler, server-side

The API key is a bearer credential – call it from your server, never from the browser. This is a Node.js handler (an API route or server action) that does the three things checkout needs: reject garbage inline, call the API server-side, and map every possible outcome – including the outage codes – to a VAT decision.

// checkout/vat-decision.ts — server-side only. Never call this from the browser.

const EU_VAT_PATTERNS: Record<string, RegExp> = {
  DE: /^DE\d{9}$/,
  FR: /^FR[A-HJ-NP-Z0-9]{2}\d{9}$/,
  NL: /^NL\d{9}B\d{2}$/,
  // ...one entry per country you support at checkout, EL for Greece
}

function isPlausibleVatId(input: string): boolean {
  const cleaned = input.replace(/\s/g, '').toUpperCase()
  const prefix = cleaned.slice(0, 2)
  const pattern = EU_VAT_PATTERNS[prefix]
  return pattern ? pattern.test(cleaned) : false
}

type VatDecision =
  | 'no_vat_id' // field left blank — charge VAT, no decision to make
  | 'eligible_for_exemption' // completed valid:true — one condition met, not the only one
  | 'invalid_vat_id' // completed valid:false or bad format — charge VAT, ask to re-enter
  | 'pending_recheck' // VIES didn't answer — charge VAT provisionally, reconcile before invoicing
  | 'blocked_config' // your own quota/requester problem — charge VAT, alert ops, don't retry

async function decideVatTreatment(rawVatId: string | null): Promise<{
  decision: VatDecision
  checkId?: string
  consultationNumber?: string | null
}> {
  if (!rawVatId) return { decision: 'no_vat_id' }

  if (!isPlausibleVatId(rawVatId)) {
    // INVALID_FORMAT — caught inline, no network call
    return { decision: 'invalid_vat_id' }
  }

  const cleaned = rawVatId.replace(/\s/g, '').toUpperCase()

  let res: Response
  try {
    res = await fetch(`https://api.vatnode.dev/v1/vat/${cleaned}`, {
      headers: { Authorization: `Bearer ${process.env.VATNODE_API_KEY}` },
      signal: AbortSignal.timeout(8000),
    })
  } catch {
    // Network failure or timeout — the same "no answer" class as an outage.
    // Never let a hanging request block the checkout.
    return { decision: 'pending_recheck' }
  }

  if (!res.ok) {
    const { error } = await res.json()
    switch (error.code) {
      case 'VIES_UNAVAILABLE':
      case 'UPSTREAM_TIMEOUT':
      case 'VIES_ERROR':
      case 'INTERNAL_ERROR':
        // VIES didn't answer — retryable. Charge VAT now, reconcile later.
        return { decision: 'pending_recheck' }
      case 'INVALID_FORMAT':
        // Slipped past the inline check (a looser regex than the API's).
        return { decision: 'invalid_vat_id' }
      case 'RATE_LIMITED':
      case 'INVALID_REQUESTER':
        // Your own quota or requester config, not the buyer's — a retry won't
        // fix these. Charge VAT and alert ops; don't queue them for recheck.
        return { decision: 'blocked_config' }
      default:
        return { decision: 'pending_recheck' }
    }
  }

  const data = await res.json()
  // { valid, vatId, countryCode, countryName, companyName, companyAddress,
  //   checkId, verifiedAt, source, consultationNumber }

  if (data.valid) {
    return {
      decision: 'eligible_for_exemption',
      checkId: data.checkId,
      consultationNumber: data.consultationNumber,
    }
  }

  return { decision: 'invalid_vat_id', checkId: data.checkId }
}

eligible_for_exemption is named that way on purpose. A valid: true result is one condition met, not clearance to zero-rate the order – for goods you still need the transport evidence, a correct EC Sales List entry, and the buyer VAT-identified in a member state other than where dispatch begins (Art 138(1)(b)): a valid same-country ID is a domestic supply, not an exempt intra-Community one. For services you still need the place-of-supply analysis to actually put the customer in scope of the reverse charge. Route the decision, don’t shortcut it:

function applyVatDecision(decision: VatDecision, order: { netTotal: number; vatRate: number }) {
  switch (decision) {
    case 'eligible_for_exemption':
      // For goods, also confirm the buyer is VAT-identified in a member state
      // other than where dispatch begins (Art 138(1)(b)) before zero-rating —
      // a same-country valid ID is a domestic supply. Recalculate from net; do
      // not derive this by subtracting VAT from a gross figure already shown.
      return { total: order.netTotal, vatApplied: false, needsReconciliation: false }
    case 'pending_recheck':
      return {
        total: order.netTotal * (1 + order.vatRate),
        vatApplied: true,
        needsReconciliation: true, // reconcile before the invoice is issued
      }
    case 'blocked_config':
      // Your validation is broken, not the buyer's number. Charge VAT so the
      // order completes, and alert ops — this needs a human, not a retry.
      return {
        total: order.netTotal * (1 + order.vatRate),
        vatApplied: true,
        needsReconciliation: false,
        needsOps: true,
      }
    case 'invalid_vat_id':
    case 'no_vat_id':
      return {
        total: order.netTotal * (1 + order.vatRate),
        vatApplied: true,
        needsReconciliation: false,
      }
  }
}

The safe default on an outage is the seller’s own domestic VAT of the dispatch member state – not the buyer’s country rate. Charging the buyer’s-country rate is an OSS/distance-selling mechanism for a different scenario and is out of scope here; applying it as a fallback for a B2B intra-Community order is the wrong number.

Recalculating the total when the VAT ID lands late

The awkward UX case: the customer sees a VAT-inclusive total, then pastes a VAT ID mid-checkout. Two mistakes are common here:

Subtracting VAT from the displayed gross figure instead of recalculating from net – rounding differences between the two make the invoice not match what the customer thinks they agreed to pay.
Re-running the check against whatever was in the field when the page first loaded instead of the final value the customer submits – a check against a half-typed ID doesn’t cover the order.

Recompute from netTotal, and re-run decideVatTreatment against the exact string that’s about to be submitted, not a cached earlier attempt.

Handling the outage case honestly

pending_recheck isn’t a dead end, it’s a queue entry. Charge VAT provisionally per the decision above, let the order complete, and reconcile before the invoice goes out – the invoice is the document that has to be right, not the checkout screen.

async function reconcileBeforeInvoicing(order: { id: string; vatId: string }) {
  const { decision, checkId, consultationNumber } = await decideVatTreatment(order.vatId)

  if (decision === 'eligible_for_exemption') {
    await markOrderZeroRated(order.id, { checkId, consultationNumber })
  }
  // else: the provisional VAT-inclusive charge stands — nothing to reverse
}

A national tax authority or company registry can sometimes answer even when VIES itself is unavailable – see coverage for which countries have that fallback. When one does answer, source reports the registry that responded and consultationNumber is null, because national answers don’t produce one; only a requester-qualified VIES answer does. Design your reconciliation job to treat both the same way operationally – it’s the valid value that drives the invoice, not which source produced it. The retry-window and backoff mechanics for the outage case itself are covered in the VIES downtime guide, and the full error-code-to-behavior mapping is in handling VIES errors in code.

What to store per order

The evidence has to attach to the order, not float in a separate log you’d have to cross-reference later:

async function persistOrderVatCheck(
  orderId: string,
  data: {
    vatId: string
    valid: boolean
    source: string
    consultationNumber: string | null
    checkId: string
    verifiedAt: string
  }
) {
  await db.insert('order_vat_checks', {
    order_id: orderId,
    vat_id: data.vatId,
    valid: data.valid,
    source: data.source,
    consultation_number: data.consultationNumber, // nullable
    check_id: data.checkId,
    verified_at: data.verifiedAt,
  })
}

Once the order is placed, this row is append-only – a re-check produces a new row, never an edit to the one taken at checkout. The consultation number, where one exists, is the European Commission’s own reference tying a specific requester-qualified lookup to a moment in time – useful evidence, not proof of the buyer’s eligibility by itself. More on what it does and doesn’t certify: the VIES consultation number explained.

One call for the whole checkout flow

The EU VAT validation API runs the VIES call, falls back to a national source when VIES can’t answer, and returns the outcome plus the evidence fields in one response – no SOAP parsing, no separate registry integration to maintain. Set your own VAT as the requester in dashboard Account details and each fresh VIES answer also carries a consultation number; leave it unset and you keep the national fallback instead. The two are a config choice, not both at once – a requester-qualified call has no fallback, so a VIES outage there surfaces as one of the error codes above, which your pending_recheck path already handles. More on that trade-off in the VIES consultation number explained.

const res = await fetch('https://api.vatnode.dev/v1/vat/FR40123456824', {
  headers: { Authorization: `Bearer ${process.env.VATNODE_API_KEY}` },
})

const data = await res.json()
// {
//   "valid": true,
//   "vatId": "FR40123456824",
//   "countryCode": "FR",
//   "countryName": "France",
//   "companyName": "Example SAS",
//   "companyAddress": "1 rue de Rivoli, 75001 Paris",
//   "source": "VIES",
//   "consultationNumber": "WAPIAAAAX9999999", // null unless a requester VAT is set
//   "checkId": "019d2a89-a5d9-7b97-b710-57b84604de2b",
//   "verifiedAt": "2026-09-07T08:30:00.000Z"
// }

For a French buyer, that’s the France VAT API reference; the same shape applies across every supported country under /vat-api. If you’re building into WooCommerce rather than a custom checkout, the WooCommerce VAT validation plugin wires the same check into the order flow without custom code. For a Stripe-based checkout, Stripe VAT validation covers that integration point. To re-check many pending orders at once, POST /v1/vat/bulk accepts up to 50,000 VAT IDs and returns a jobId: you poll the job, then page its results. Each position does carry checkId, but not verifiedAt, companyName or companyAddress, so keep using the single call where an order needs all the evidence fields. See the API reference and the error reference for the full code list.

This is general information about EU VAT and VIES, not tax advice. Whether a specific order qualifies for zero-rating or reverse charge depends on facts we can’t assess here – dispatch location, transport evidence, the buyer’s actual status – confirm the treatment of your own transactions with a qualified tax adviser.

FAQ

Should a VAT ID field block checkout if it can’t be validated instantly?

No – the VIES call is server-side and has no SLA, so waiting on it before allowing payment turns a temporary outage into a lost order. Let checkout complete, apply a provisional VAT treatment, and reconcile before the invoice is issued.

Is validating a VAT ID at checkout about reverse charge or VAT exemption?

It depends on what’s in the cart. For goods, a valid buyer VAT ID is a substantive condition for zero-rating the intra-Community supply. For services, it supports treating the customer as a taxable person under the reverse charge, where the customer self-accounts for VAT. They’re different regimes with different legal bases – don’t treat ‘reverse charge’ as the umbrella term for both.

What happens if a customer enters a valid VAT ID after the order total is already shown?

Recalculate the order total from net, not by subtracting VAT from the gross figure already shown, and re-run the check against the final VAT ID before payment – a validation done against an earlier or partial number doesn’t cover the order.

Do I need to re-check the VAT ID before issuing the invoice?

Yes if the checkout answer was provisional – a pending state from a VIES outage, or a check that ran before the customer finished editing the field. If checkout already returned a completed, valid answer for the exact ID on the order, that check is your evidence; you don’t need to repeat it just because time has passed.

Validate VAT IDs from your own checkout flow

The EU VAT validation API runs the VIES call, falls back to a national source on downtime, and returns the outcome plus the evidence fields in one response – no SOAP parsing. Get a free API key: free plan, 100 requests/month.

DEV Community: Iurii Rogulia

The Typography Details Your Visitors Notice Without Knowing Why

What ‘Right’ Actually Looks Like

Even a Careful Site Gets This Wrong

The Bigger Pattern This Is Standing In For

Who This Actually Matters To

How to Spot a Fake Pay Stub: A Reviewer’s Guide

The Visual Checklist

1. Does the math actually add up?

2. Do the deductions make sense for the numbers shown?

3. Fonts and alignment

4. Employer details that don’t line up

5. Formatting that doesn’t match the claimed provider

6. Inconsistent or implausible dates

7. File metadata, if you can see it

Where This Checklist Runs Out

The Layer That Answers the Other Question

What This Doesn’t Solve Either

Building This Into a Review Process

Related Reading

The Short Version

VAT Vendor Verification for Marketplaces

VAT Validation for Multi-Vendor Marketplaces: Who Checks Whom

Validating Vendors at Onboarding

Validating Business Buyers

Deemed Supplier: Where the Platform Itself Gets Pulled In

Audit Evidence, at Marketplace Scale

Ongoing Monitoring Across Many Vendors

Doing This in Code

FAQ

Does a marketplace have to validate seller VAT numbers?

How often should a platform re-check vendor VAT IDs?

Does vatnode validate both vendors and buyers on a marketplace?

What about deemed-supplier VAT rules for marketplaces?

Validate vendors and buyers from one API

Caching VAT and FX Rates at Build Time, Not on the Request Path

The Prebuild Script

‘Never Fails the Build’ Is the Load-Bearing Line

Dev Mode Never Touches the Network for This

VAT Rates: Same Instinct, Different Failure Direction

Where a Build-Old Number Is Fine, and Where It Isn’t

The Alternative Nobody Admits to Shipping

Do Mortgage Underwriters Actually Verify Bank Statements?

What the Asset File Is Actually Made Of

Bank statements, read for sourcing and seasoning

The Verification of Deposit

Employment and income, cross-referenced

The automated path, where the document disappears

Where the PDF Path Survives

The Question the Stack Does Not Ask

The Residual Question: Was the File Changed After Issue?

What This Layer Is Not

Wiring It Into an Asset Review

What Happens When You Reverse-Charge an Invalid VAT Number

What Happens When You Reverse-Charge an Invalid VAT Number

Reverse charge is a services mechanism, not a goods one

What ‘invalid’ actually costs the seller

The good-faith defence – and its limits

Format-valid is not the same as registered

What an invalid result actually looks like – and why it’s useful

Where the actual exposure comes from

FAQ

Who owes the VAT if the buyer’s number turns out to be invalid?

We validated at invoice time and the number was deregistered later – are we exposed?

Does a VIES outage mean the buyer’s VAT number is invalid?

Is a VIES screenshot enough evidence if this gets audited later?

Know before you invoice, not after an audit

Booking a Shipment from an Order Pipeline Without Stalling the Rest of the Order

Does the Booking API Answer Now, or Later?

Should a Slow Carrier API Stall the Customer’s Invoice?

A Booking That Succeeded but the Response Got Lost

How to Check a PDF’s Creation & Modification Dates

Where the two dates live

How to check a PDF’s creation date online or offline

Why the raw values lie

What a plain glance at the dates can’t tell you

Gaps that are normal, and gaps that aren’t

What a structural check adds

Reading a structural result

Common questions