The VAT whitelist
in Medusa
Verify a Polish NIP against the Ministry of Finance whitelist, EU VAT numbers against VIES, and the REGON and legal form against the GUS Business Registry, right where the store is run. The VAT status, the bank accounts for split payment, a counterparty list with re-checks, the check history and the registration form's preview.
What exactly
this integration does
-
The format picks the registry
A 10-digit Polish NIP goes to the whitelist (and GUS, when the key is set), a number that looks like an EU VAT number goes to VIES. Invalid numbers answer without a network call.
-
One row per counterparty
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.
-
Split payment accounts
The registry's bank accounts are kept per counterparty, so an invoice can carry the account the whitelist confirms.
-
History as the audit trail
Every run per registry is kept as the audit trail and never changed – a control has something to return to.
-
The registration form fills itself
A public, rate limited preview pulls the company card from the NIP before sign-up, so the form writes 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 – verifying the counterparty happens on their side.
How it guards
your data
-
Freshness with a limit
An answer stays valid for staleHours (a day by default), the panel marks stale counterparties, and a re-check asks the registry again.
-
Demo mode never leaves the server
Checks answer with simulated registry data, flagged demo. Turned on only by demo: true, never by a missing key.
-
The preview is rate limited
The public registration preview is limited per address, so it never becomes a free NIP lookup for the whole internet.
Setup
in three steps
The full list of options, events and API routes is in the package README on GitHub.
Paste it into Claude Code, Cursor or another AI assistant in your Medusa project: it installs and configures the integration, with writes off.
- 1 Install the package from npm.
npm install @koda-plus/medusa-plugin-vat-whitelist - 2 Add the plugin to medusa-config.ts.
plugins: [ { resolve: "@koda-plus/medusa-plugin-vat-whitelist", options: { // Everything is optional. staleHours: 24, // gusApiKey: process.env.GUS_API_KEY, // BIR 1.1, dla rejestru GUS // demo: process.env.WHITELIST_DEMO === "true", }, }, ] - 3 Run the migrations and open the integration in the Medusa admin.
npx medusa db:migrate
Running for our clients
See our portfolio
Other
integrations
- Allegro Offers, orders, stock and parcels
- BaseLinker Cards, stock, prices and orders both ways
- Subiekt nexo Orders as ZK, WZ and invoices with KSeF
- Fakturownia Invoices, corrections and KSeF exactly once
- InPost Parcel lockers, courier and COD on ShipX
- OLX Adverts that match the store's stock
- Stripe Volume, fees, disputes and account health
- Negotiations Target price, counter offer, acceptance
- Trade credit Limits, terms and customer balances
- Loyalty Points, a reward ladder and a ledger
- Packaging Piece, box, pallet, minimum and step
- EU compliance GPSR, RODO and Omnibus in one panel
- E-mails Ready templates in Polish and English
- Tasks Tasks on orders, products and customers
Tell us about your project,
we'll tailor the rest to you
A 15-minute call is enough for us to know whether we are a fit for your project.
We start from what you need, not from an off-the-shelf solution.