QR Codes

Every ULink link has a QR code generated automatically — there is nothing to enable. The QR encodes the link's short URL, so a scan goes through the exact same resolution and attribution path as a tap: deep link on app open, fallback to the store or web otherwise.

Scans are tagged as QR traffic (the encoded URL carries a _qr=1 marker), so you can tell scans apart from taps in analytics.

Getting the QR image

The QR is served from a public, cacheable URL — drop it straight into an <img> tag, an email, a slide, or a print layout. No API key or login required.

GET https://api.ulink.ly/api/v1/links/{linkId}/qr.{format}

• {linkId} — the link's ID (the id field returned when you create a link, or the link's row in Dashboard → Links). This is the UUID, not the slug.
• {format} — one of png, svg, or pdf.

<!-- Embed directly -->
<img src="https://api.ulink.ly/api/v1/links/3f2a.../qr.png" alt="Scan to open" />

Responses are cached for 5 minutes (Cache-Control: public, max-age=300).

Formats

Format	Best for	Notes
png	Web, email, quick embeds	Raster, rendered at 1024 px wide
svg	Web, design tools	Vector — scales to any size with no quality loss
pdf	Print, packaging, posters	Print-ready document. Paid plans only (free plans receive 402 Payment Required)

Branding (paid plans)

On free plans the QR renders in the default black-on-white style. Paid plans can customise the look from Dashboard → Links → (a link) → QR:

• Colors — foreground and background (any solid hex color).
• Module shape — square, dot, or rounded.
• Eye shape — the three corner markers: square, rounded, or circle.
• Caption frame — a short label rendered under the code (up to 40 characters).
• Logo — an image centered in the code. Upload it through the dashboard; the error-correction level is raised automatically so the code still scans with a logo on top.

Styling is saved per link and applies to every format and every embed of that link's QR.

Saving a style programmatically

The dashboard saves styles for you. If you are scripting against your own account, the same endpoint is available with a dashboard (Supabase) session — note this is not an API-key endpoint:

PUT https://api.ulink.ly/api/v1/links/{linkId}/qr
Authorization: Bearer <supabase-session-jwt>
Content-Type: application/json

{
  "style": {
    "fg": "#0B5FFF",
    "bg": "#FFFFFF",
    "moduleStyle": "rounded",
    "eyeStyle": "circle",
    "frame": { "caption": "Scan to download" },
    "logo": ""
  }
}

Styling endpoints return 402 Payment Required on free plans. Colors must be 6-digit hex; moduleStyle, eyeStyle, and the caption length are validated strictly, and logos may only be served from ULink storage.

Tips

• The QR never changes when you update the link's destination — print it once, re-point the link whenever you like.
• Use svg for anything that will be resized (billboards, packaging); use png when you just need a file to drop into a doc.
• Keep at least a small quiet margin around the code when you place it on a busy background so scanners can lock on.