Copy page

How to start

Order Flow

A read-once reference for partners building any integration with Vignette ID. This page maps the moving parts (your backend, our API, the national provider, your webhook endpoint) to the events they exchange so you can wire your system correctly the first time.

If you only have five minutes, skip to the sequence diagram — it shows the full happy path from POST /orders to the PDF confirmation.

---

Choose your integration

We support three integration shapes. Pick one based on how much UI control you need vs. how fast you want to ship.

Path	Best for	Time to live	Customization
API	Established partners with their own checkout	2–6 weeks	Full
Widget	Travel sites, content sites, MVP launches	1–3 days	Theme + presets
Iframe	Affiliates, blogs, no-code sites	< 1 hour	Locale + theme

---

End-to-end order flow

A robust integration is shown as one timeline: pre-flight checks, then bounded-retry order creation, then the async lifecycle driven by webhooks. Status names match /wiki/statuses; webhook events match /wiki/webhooks.

Why each step matters

1. GET /products/status on page load — country and period availability can flip mid-day (national provider outage, maintenance window). Run this before rendering the form, not at submit time, so unavailable countries / durations are hidden in your UI rather than "click to find out". Cache the response for ~60 s — there's no reason to hammer the endpoint on every page hit.
2. POST /validate-vehicle after the user enters the plate — catches typos (Cyrillic chars, malformed VINs, missing dashes for AT/DE) on the cheap server-side check before spending an order attempt. Failed validation costs nothing; a failed POST /orders costs an idempotency slot and can leave a partial record. Run it on form submit (or onBlur of the plate field for inline UX).
3. POST /orders outcomes:
   • 200 — keep the returned id, persist it locally, then watch webhooks.
   • 409 (or equivalent duplicate signal) — stop trying. Re-querying with the same body will produce the same answer. Surface the existing order to the user.
   • 5xx / network errors — transient. Retry once per minute, max 5 attempts (≈5-minute total window). After that, surface a "we couldn't process your order" screen and notify on-call.
   • 4xx other than 409 — your request is malformed (bad plate format, invalid product). Don't retry; fix the input.

Failure & cancellation paths

---

Status reference

Every status you'll see in webhook payloads or GET /orders/{id}/status:

Status	When you see it	What to show the user
CREATED	Right after POST /orders succeeds	"Processing your order…"
DEFERRED	Start date > 3 days from purchase	"Vignette scheduled for <date>"
PENDING	Awaiting national provider	"Processing your order…"
WILL BE ACTIVE	Provider registered, awaiting unique ID	"Almost ready…"
ACTIVE	Vignette is valid — user can drive	"✅ Vignette is active"
EXPIRED	Validity period ended naturally	"Expired on <date>"
REFUNDED	Cancelled or charged back	"Refunded"
DELETED	Unknown error, contact support	Show error + support link

Full descriptions and cancellation windows: Statuses list.

---

Don't poll — listen for webhooks

GET /orders/{id}/status is rate-limited to 15–25 req/min per order ID (rate limits) precisely because polling is the wrong tool here.

Webhook payload format and signature verification: Webhooks.

---

Next steps

• API → API References for endpoint specs.
• Widget → Widget Integration for the embed snippet.
• Iframe → Iframe Integration for the no-code path.
• Need a call? Reserve an integration meeting slot.