Quickstart: read the catalogue without a key
Three GET endpoints, no authentication, CORS open, JSON responses. Start from the country list, then fetch prices for the country you need.
- GET https://e-vignettes.eu/api/v1/countries — the nine covered countries, their toll operator and a summary of each toll system.
- GET https://e-vignettes.eu/api/v1/countries/at — the full Austria guide: tolled roads, vehicle categories, activation, fines, section tolls, FAQ and the official sources each fact was checked against.
- GET https://e-vignettes.eu/api/v1/products?country=at&type=vignette — live prices, with the government price and the service fee as separate fields.
Errors
Every failure, including an unmatched /api/ URL, returns JSON rather than an HTML error page, always with the same shape: a stable code to branch on, a human message, a hint naming what to change, the HTTP status, and a documentation_url. The six codes are part of the contract and are never renamed; the reference lists each one with its status and what it means.
Selling vignettes: the partner API
Creating an order, validating a vehicle, cancelling or modifying an order and receiving webhooks all happen on the authenticated partner API, on a different host from everything above. Production is https://api.vignette.id and the sandbox is https://sandbox-api.vignette.id, with the endpoints under /public: products, orders, users and validate-vehicle.
Authenticate with an Authorization header of the form Bearer followed by your partner API key. Sandbox and production are separate environments with separate keys, and a key from one is rejected by the other. Build against the sandbox first: the whole order lifecycle, webhook events and cancellations included, works there without touching real payments or government systems.
Every endpoint, with its schemas, parameters and examples, is documented on the partner documentation site rather than repeated here. One reference, kept next to the API it describes, cannot drift from it the way a copy would.
- Partner API reference — every endpoint
- Partner Panel — Where your sandbox and production keys live, under For Developers
- Partner programme and registration form
Three ways to integrate
Three integration shapes are supported, and the trade-off is UI control against time to live. The REST API gives you full control of the checkout and takes the longest to build. The web widget renders the entire purchase flow — country, vehicle type, duration, vehicle details and payment — inside your own page from a script tag. The iframe is the fastest: configure language, currency, theme and environment in the Partner Panel, paste the block, and you are taking payments the same day.
The widget loads from https://widget.vgnt.app/vignette-widget.js and is initialised with your API key and an API base URL, so the same key and the same sandbox host apply as on the REST API. The iframe carries its settings as query parameters, including env=sandbox while you test, and an optional subaccount parameter if you want separate reporting per campaign or traffic source.
The Partner Panel is not a fourth integration. It is the dashboard every partner uses whichever route they take: creating orders by hand, watching sandbox and production orders separately, and configuring webhooks and redirects.
Getting a key and going live
Registration is a human step, not an API call: no endpoint issues a credential. Apply through the partner form, and the team creates your account and issues both keys, which you read in the Partner Panel under For Developers. Developers are added to the account in the same panel, under Profile, Settings, Members.
Configure two things there before you write code: the webhook URL that order status changes are delivered to, and the success and error redirect URLs a customer returns to after payment. Polling for status instead of receiving it is exactly what the partner rate limits are shaped to discourage.
Going live is commercial rather than technical. The revenue calculator is where you choose the payment model, the commission model and the countries you want to sell, and download the pre-filled draft cooperation agreement; a refundable security deposit follows — 1,000 EUR when Vignette ID processes the payments, 3,000 EUR when you collect them yourself. The production key is activated once the deposit is received and the agreement is signed.
Support, rate limits, payout frequency and the option to remove Vignette ID branding follow a tier: Standard is free, Premium is 49 EUR a month and Enterprise is 150 EUR a month. Which countries are open to new partners is stated in the calculator, and it is not always every country in the public catalogue above.
Order lifecycle, webhooks and corrections
An order does not complete inside the request that creates it. It is created, sent to the national provider, and becomes active when that provider confirms, which is why status arrives as a webhook event rather than as a return value. Subscribe to the webhook and treat the status endpoint as a fallback, not as a loop.
An order can no longer be modified once it reaches pending. If your customers need to correct a licence plate, a country of registration or a start date after that point, Flex Service is the product that allows it, selected per product on the order: one plan covers changes up to a few hours before the vignette starts, the other covers changes while it is already active.
Pending and deferred orders each have their own cancellation endpoint. Whether an already active vignette can be refunded depends on the national operator's rules for that country and product rather than on us, so do not promise your customers a cancellation the provider does not offer.
MCP server: read the catalogue as tools
This site runs its own Model Context Protocol server at https://e-vignettes.eu/mcp, over Streamable HTTP. It needs no credentials and exposes the read API as four tools: list_countries, get_country, list_products and read_page, the last of which returns any page of the site as Markdown.
It is stateless and dual-era: it serves the current per-request-metadata revision of the protocol, 2026-07-28, and still answers the initialize handshake used by 2025-11-25 and earlier, so older clients keep working. There is no SSE stream and no session; GET and DELETE answer 405, as that revision requires.
Errors come in two kinds, as the protocol specifies. A call the server refuses — a tool that does not exist, or an argument outside the tool's schema such as a country code it does not cover — is a JSON-RPC error with code -32602, whose data names the parameter, the value received and the allowed values, so an agent can correct the call. A tool that ran but could not answer — the live catalogue unreachable, a page that does not exist — is an ordinary result with isError set and an explanation to relay or retry on.
Point any MCP client at the endpoint, or read the manifest below to discover it programmatically. The server cannot buy anything — see the partner server for that.
A2A agent: delegate the question instead of calling tools
For orchestrators that speak the Agent-to-Agent protocol rather than MCP, the same catalogue is an A2A agent at https://e-vignettes.eu/a2a: JSON-RPC 2.0 over POST, protocol version 1.0, no credentials. Its four skills are the four tools of the MCP server — the countries covered, one country's toll rules, today's prices, and any page of the site as Markdown — each returned as a completed task with the answer as text and as structured JSON.
It is stateless: every SendMessage completes inside its own response, so there is nothing to poll, stream or cancel, and the agent card says so. A message is matched to a skill by the country it names and a few intent words, or reliably by a data part that names the skill; anything it cannot place gets a clarification message rather than a guess. Like the MCP server, it cannot buy anything.
MCP server: let an agent do the ordering
The partner API is also exposed as a Model Context Protocol server, so an LLM agent can browse the catalogue, validate a plate and place an order as tool calls instead of hand-written HTTP. Point any MCP client at the endpoint and authenticate with the same partner API key, sent as an Authorization header of the form Bearer followed by the key; the key lives in the Partner Panel under For Developers.
Build against the sandbox server first — https://sandbox-api.vignette.id/mcp — and switch to https://api.vignette.id/mcp only when you are ready to place real orders. Sandbox and production keys are separate.
The server exposes 11 tools: get_products, get_products_status, get_users, get_user_orders, validate_vehicle, create_order, get_orders, get_order, get_order_status, cancel_pending_order, cancel_deferred_order. A typical purchase is get_products to find the product, validate_vehicle to check the plate, create_order to buy, then get_order_status to follow it from PENDING to ACTIVE.
Rate limits
The public endpoints are limited per IP address under two policies: 240 requests per 60 seconds across /api/v1, and 120 per 60 seconds on the MCP endpoint, which is lower because one tool call can fan out to nine upstream requests. Every response carries RateLimit-Policy and RateLimit, so read them and self-throttle rather than discovering the limit with a 429. The reference gives the header format and the exact fields.
The partner API counts differently: per partner and per route rather than per IP, and per resource ID on the routes that carry one, so a busy order cannot spend another order's budget. The quotas rise with your tier, and their shape tells you the intended design — creating an order is measured in hundreds per minute, while checking one order's status is measured in tens, because status is meant to reach you as a webhook. Cache the catalogue instead of calling it per checkout, and read the current table before you tune a retry loop.
Versioning and deprecation
The public API is versioned in the URL path: /api/v1 is current, and a breaking change gets a new path rather than altering v1 underneath you. Additive changes are not breaking, so parse defensively. A retirement is announced in the responses themselves, with Deprecation, Sunset and Link headers, and a deprecated version keeps answering for at least 12 months after that announcement. The reference states the full policy, header by header.
Client libraries
No client library is published for the public read API, in any language, and none is planned. Three unauthenticated GET endpoints returning JSON are less code to call than a wrapper is to maintain, and a wrapper is one more thing that can fall behind the contract.
Where types and error handling are worth having, generate them: the OpenAPI document is valid 3.1 with a unique operationId and a typed schema on every response, so openapi-generator, Kiota, oapi-codegen and similar tools consume it without hand-editing. The client page walks through that and through calling the endpoints directly.
For AI agents
This site answers Accept: text/markdown with Markdown on every content page, including the homepage and the country guides, so a page can be read without parsing HTML. Unknown paths return a 404 with a Markdown body pointing at the site map.
A site summary in llms.txt format, an expanded companion with per-country facts and live prices, and a when-to-use brief for agents are all published as plain text.
Discovery documents
Everything above is discoverable without reading this page. An agent that knows only the domain can walk the well-known paths and find the rest.
- API catalog (RFC 9727 linkset) — Points at the OpenAPI document, these docs and the health check
- Capability manifest (ARD / ai-catalog) — Every machine-readable surface, with the questions each one answers
- MCP manifest (registry server.json)
- Entry in the official MCP Registry — eu.e-vignettes/vignette-id, published and verified against this domain
- Listing on Smithery — The same read-only server, reachable through the Smithery gateway
- Agent skills index — Three SKILL.md documents with SHA-256 digests
- A2A agent card — Agent-to-Agent protocol 1.0: the read skills as a JSON-RPC agent at /a2a
- Pricing (Markdown) — Every vignette and toll price, the TollBox plans and the partner tiers as tables
- Schema map (NLWeb Schema Feeds) — The site's JSON-LD as JSON Lines feeds: products with offers, country guides
- How to authenticate — Short version: tier 1 needs nothing
- Health check
Tools in the browser (WebMCP)
Every page on this site registers read-only tools with the browser's WebMCP model context when the browser supports it, so an agent working inside the reader's tab can look up countries, toll rules and prices, and open a country guide or the shop, without leaving the page or calling the API itself.
Registration happens in an inline script in the document head, before the page's own JavaScript loads, through document.modelContext.registerTool; navigator.modelContext and the older provideContext method are feature-detected as fallbacks. The homepage also carries the declarative form of the same API: the find-your-vignette form is annotated with toolname and tooldescription, so a supporting browser exposes it as a tool whose parameters are the form's fields. In a browser without WebMCP nothing is registered and nothing is logged.
Getting help
Integration questions, API keys and commission terms: work@vignette.id. An integration call with the team is available if you want to walk through the API or the iframe setup before writing code.
- Vignette ID on GitHub — The organisation profile: what we build, the apps and the TollBox