VAT Whitelist (PL/EU)
Verify Polish NIP and EU VAT numbers
VAT Whitelist by Koda Plus
Verify a Polish NIP in the GUS Business Registry and the Ministry of Finance whitelist (the biala lista), and EU VAT numbers in VIES, right where the store is run. The VAT status, the bank accounts for split payment, the legal form, a counterparty list with re-checks, the check history and the registration form's preview, without another tool to log in to.
Every B2B store in Poland must check who it sells to: an active VAT payer on the whitelist, with a bank account that the registry confirms. This plugin keeps the checks, the answers and the audit trail in the Medusa admin, fills the registration form from the NIP, and shows the logged-in customer the status of their own company.
Live demo: Medusa admin medusa.koda.plus/app/whitelist, signed in to a public demo account by the link itself. Demo mode answers with simulated registry data, so the public demo never calls the registries.
What it does
- Polish NIP against the whitelist: the VAT status (Czynny, Zwolniony, Niezarejestrowany), the taxpayer's name and address, and the bank accounts, from the Ministry of Finance API.
- EU VAT numbers against VIES: the validity, name and address of the business, through the VIES REST API.
- The GUS Business Registry (BIR 1.1): the company a NIP stands for, VAT payer or not: full name, address, REGON, KRS, legal form, start date, and whether the business runs, is suspended or has ended. Needs a free BIR 1.1 user key (Copy to clipboard
gusApiKey); the GUS test environment works with its public key (Copy to clipboardgusEnvironment: "test"). - Counterparties: one row per number with the latest merged answer, refreshed by a re-check; the NIP links to the customer when the check was about their company.
- Check history: every run per registry kept as the audit trail, never changed.
- The registration preview: a public, rate limited route pulls the company card from the NIP before sign-up, so the registration form fills the company name by itself.
- The customer's own status: a logged-in customer sees and refreshes the status of their company NIP through the store API.
Features
- One page in the admin: the check form with the full company card of the answer, the counterparties with their states and the check history, in English and Polish.
- The format decides the registries: a 10-digit Polish NIP goes to GUS and the whitelist (the order and the list in Copy to clipboard
plRegistries), an EU VAT number (a member state prefix and a number) goes to VIES, a NIP with the PL prefix to VIES as well. Invalid numbers answer without a network call. - One card from every registry: the company from GUS, the VAT status and the bank accounts from the whitelist, and what each registry answered. A business GUS reports suspended or ended reads Copy to clipboard
inactive. - Settings / Registries: how each registry answers with the options in use, and a connection test per registry (GUS logs in and out without spending a lookup).
- Caching and freshness: an answer stays valid for Copy to clipboard
staleHours(default 24), the panel marks stale counterparties and a re-check asks the registry again. - Split payment: the registry's bank accounts are kept per counterparty, so an invoice can carry the account the whitelist confirms.
- Demo mode (Copy to clipboard
demo: true): checks answer with simulated data, flagged Copy to clipboarddemo, and nothing leaves the server. Only ever on with Copy to clipboarddemo: true, never because a key is missing. With Copy to clipboardlive, the named registries answer for real for every number outside the demo samples (a public demo with real company data). - Store API for the logged-in customer: Copy to clipboard
GET /store/whitelist/me(their status, reads only) and Copy to clipboardPOST /store/whitelist/check(a fresh check of their own NIP).
Requirements
- Medusa 2.12 to 2.21 and Node.js 20+ (see Compatibility).
- Postgres, as every Medusa store has.
- Outbound HTTPS to GUS (wyszukiwarkaregon.stat.gov.pl), the Ministry of Finance whitelist API and VIES (nothing is needed in demo mode).
- For GUS: a BIR 1.1 user key, free from GUS by e-mail (regon_bir@stat.gov.pl).
Installation
1npm install @koda-plus/medusa-plugin-vat-whitelist
Yarn and pnpm work the same way: Copy to clipboardyarn add @koda-plus/medusa-plugin-vat-whitelist or Copy to clipboardpnpm add @koda-plus/medusa-plugin-vat-whitelist.
Configuration
Add the plugin to Copy to clipboardmedusa-config.ts:
123456789101112131415module.exports = defineConfig({// ...plugins: [{resolve: "@koda-plus/medusa-plugin-vat-whitelist",options: {// Everything is optional.gusApiKey: process.env.GUS_API_KEY,plRegistries: ["gus", "whitelist"],staleHours: 24,demo: process.env.WHITELIST_DEMO === "true",},},],})
Run the migrations, then open Whitelist in the admin sidebar:
1npx medusa db:migrate
The migration creates two tables of the module: Copy to clipboardwhitelist_entity and Copy to clipboardwhitelist_check.
Options
Every option has a default, so the plugin starts without any.
- demo (boolean, default Copy to clipboard
false): demo mode. Checks answer with simulated registry data (including a simulated GUS answer), flagged Copy to clipboarddemo. - baseUrl (string, default Copy to clipboard
https://wl-api.mf.gov.pl): the base URL of the whitelist API, for a proxy or a mirror. - staleHours (number, default 24): a check of the same number is repeated after this many hours without asking the registry again. 0 always asks.
- gusApiKey (string, default none): the BIR 1.1 user key of the GUS Business Registry. Without it GUS is skipped in real mode.
- gusEnvironment (Copy to clipboard
productionor Copy to clipboardtest, default Copy to clipboardproduction): Copy to clipboardtestuses the GUS test environment and, without a key, its public test key. - plRegistries (list or comma-separated string, default Copy to clipboard
["gus", "whitelist"]): the registries of a Polish NIP, in order. Add Copy to clipboardviesto confirm the VAT-UE registration for sales within the EU. - live (list or comma-separated string, default none): in demo mode, the registries (Copy to clipboard
gus, Copy to clipboardwhitelist, Copy to clipboardvies) that answer for real for every number outside the demo samples. - timeoutMs (number, default 8000): how long one registry call may take.
Admin API
- Copy to clipboard
GET /admin/whitelist- the counterparties, the latest checks and the counters. - Copy to clipboard
POST /admin/whitelist/check- checks a number (Copy to clipboard{ nip }), asks its registries, creates or refreshes the counterparty and appends one check per registry. - Copy to clipboard
POST /admin/whitelist/entities/:id/check- re-checks a counterparty. - Copy to clipboard
POST /admin/whitelist/registries/ping- the connection test of one registry (Copy to clipboard{ registry: "gus" | "whitelist" | "vies" }). Saves nothing.
Store API
- Copy to clipboard
GET /store/whitelist/me- the logged-in customer's own counterparty, from the company NIP in their profile. Reads only. - Copy to clipboard
POST /store/whitelist/check- a fresh check of the customer's own NIP, linked to their account. - Copy to clipboard
POST /store/whitelist/preview- the registration form's check: the company card from a NIP (Copy to clipboard{ nip }) or an EU VAT number (Copy to clipboard{ vat_number, country_code }, the prefix added when missing), before sign-up, without saving. Public, rate limited per address, answers cached for ten minutes.
Compatibility
Medusa 2.12 through 2.21. The admin extension mounts through the Medusa admin SDK; the plugin's admin libraries are optional peers, so the app keeps the dashboard's own copies.
