Custom QR codes

Style, batch-download, automate, and troubleshoot QR codes, presets, logos, and regeneration behavior.

Custom QR codes in Nimriz

Every short link in Nimriz has a built-in QR code. By default, it uses a plain black-on-white design. With a supported plan, you can customize the appearance-colors, shapes, gradients, logos, and CTA frames-to match your brand.

Prerequisites

A Nimriz workspace on a plan that includes the QR capabilities you need. Use Plan availability by tier below for the exact feature list on Starter, Plus, Growth, Professional, and Enterprise.

Plan availability by tier

Each higher tier includes the QR features from the tiers below it. Preset and frame limits here reflect the defaults on self-serve plans. Your Enterprise contract may add commercial or policy terms on top of this feature set.

Starter

Download a standard black-on-white QR code (PNG or SVG) for any short link.

Plus

Everything in Starter.
Full styled QR editor: colors, gradients, module shapes, corner eyes, and logos.
Transparent backgrounds in PNG and SVG exports.

Growth

Everything in Plus.
Save up to 3 workspace QR presets and reuse them across links.
Use 3 built-in QR frame templates with fixed CTA phrases.
Open the QR Performance view in analytics for QR scans and QR-origin traffic.
Run bulk QR ZIP exports from the Links table.

Professional

Everything in Growth, with preset and frame limits raised to 10 presets and 6 frame templates.
Set custom CTA text inside supported frames (within scan-safety rules).
Use the live QR heatmap on QR Performance and on Realtime when you filter to QR triggers.
Call the customer QR API to generate assets and manage presets programmatically.

Enterprise

Everything in Professional, with workspace preset capacity raised to 25 (the frame template library stays at 6, the same set as Professional), unless your agreement states otherwise.

How QR analytics work

When a visitor scans a Nimriz QR code, the platform automatically identifies the scan as QR-origin traffic.

Nimriz embeds a special parameter (?nr=qr) in the URL encoded into the QR image. When the Nimriz edge receives that request, it records the event with touch_type = qr_scan instead of short_link_click. This gives you separate visibility into QR scans versus standard short URL clicks in your analytics dashboard.

You can view QR performance directly in the dedicated QR Performance tab in your analytics dashboard (Growth+ plans), which isolates scans, QR-origin traffic share, and top QR-enabled links. On all plans, you can also filter the main analytics overview by Trigger = QR.

On Professional plans, the QR Performance view also includes a Live QR heatmap module. It uses the recent Realtime window to show a country heatmap plus top regions and cities for QR scans only.

The ?nr=qr parameter is stripped from the final destination URL-it never reaches your website or appears in your server logs. Your destination URL remains clean.

Live QR heatmap (Professional+)

The live QR heatmap is designed for short-window monitoring rather than historical reporting.

It uses the same recent Realtime window as Nimriz's live analytics view.
It appears on the QR Performance page and on Realtime when you filter Trigger = QR.
It works at the full-workspace level, or when you scope the view to one domain or one link.
Region and city values are best-effort and may show as Unknown when the request metadata is incomplete.

Customization options

Option	What you can customize
Foreground color	The color of the QR data modules (the dark squares and dots).
Background color	The color behind the QR pattern. Transparent backgrounds are available on Plus plans and above.
Gradient	Apply a linear or radial color gradient across the foreground pattern.
Module shape	Change the style of individual data squares-square, rounded corners, circles/dots.
Corner eye style	Customize the three large corner positioning squares independently from the data modules.
Logo	Upload a custom brand logo to be centered within the QR code. Nimriz automatically increases the error-correction level when a logo is used.
Quiet zone	Adjust the white-space padding around the outer edge of the QR code.
QR frame	Add a reusable CTA frame above or below the code with editable colors, spacing, and CTA copy. Growth includes the first template set; Professional adds more templates and custom CTA text.

Downloading your QR code

You can download any QR code in two formats:

SVG (Scalable Vector Graphics)

Recommended for print materials, large-format displays, and any context where you need to scale without quality loss.
Supports transparent backgrounds.
Can be opened and further edited in vector design tools like Figma, Illustrator, or Inkscape.

PNG (raster image)

Recommended for digital use: slide decks, email headers, documents, and social posts.
Available in multiple pixel sizes (e.g., 512px, 1024px, 2048px).
Supports transparent backgrounds (alpha channel).
For print materials, use at least 1024px. For large-format printing, use SVG instead.

Rule of thumb: Always use the SVG format or the highest-resolution PNG when you are unsure of the final output size.

Bulk QR downloads

Growth and higher plans can queue a ZIP of QR assets directly from the main Links table.

Select one or more links in the table and use the bulk QR action in the header.
Nimriz renders each selected link from its saved effective QR state. That means saved presets, saved per-link overrides, transparent backgrounds, frames, and logos are all respected.
The first dashboard bulk flow exports png files at 1024px and queues the ZIP in Exports so the job can finish in the background.
If some links fail to render, Nimriz still prepares the ZIP when at least one asset succeeds. The archive includes a manifest.json file with the success list, failed items, and the render-source metadata used for the job.
Bulk QR downloads do not create a separate QR inventory. They operate on the QR settings already attached to your links.

QR presets

Presets let you save a QR design and apply it consistently across multiple links.

Creating a preset

Go to Library → QR presets in your workspace.
Click New preset.
Configure your colors, shapes, logo, and optional frame.
Give the preset a name and save it.

Applying a preset

When creating or editing a link, open the QR section and select a preset from your workspace's preset list. The preset's design is applied to that link's QR code immediately.

Setting a default preset

You can designate one preset as the workspace default. When team members create new links, the default preset is applied automatically, ensuring brand consistency without requiring each person to manually select a design.

Overriding a preset

You can apply a preset and then adjust individual settings (e.g., change one color or swap the logo) without modifying the original preset. The override applies only to that specific link's QR code.

QR frames

QR frames wrap the QR code in a reusable CTA layout without changing the short URL behind the code.

What ships on Growth

Banner bottom
Banner top
Badge bottom
Bounded CTA phrases such as Scan me, Learn more, Open link, View menu, and Save contact

What Professional adds

Badge top
Pill bottom
Rounded panel
Custom CTA text within the same scan-safety limits

Frame rules

Frame layouts stay above or below the QR itself rather than covering the code.
CTA text stays on one line.
Nimriz keeps extra quiet-zone space around framed codes for scan reliability.
The framed export you preview is the same layout Nimriz uses for downloads.

Design best practices for reliable scanning

Customization affects scan reliability. Follow these guidelines to ensure your QR codes always work:

High contrast is critical

QR scanners work by detecting the contrast between light and dark modules. The greater the contrast, the more reliably the code scans.

Use dark foreground on a light background, or vice versa.
Avoid similar shades of the same color (e.g., dark grey modules on a medium-grey background).
Test with your phone in low-light conditions if the code will be displayed outdoors or in dimly lit venues.

Keep the quiet zone intact

The quiet zone is the blank border around the QR code. Scanners need this space to locate the boundary of the code. If you reduce the quiet zone too aggressively or crop the image tightly, the code becomes unreliable.

Treat framed assets as full layouts

When you add a QR frame, the exported asset becomes taller than the raw square QR. Keep the full frame, CTA band, and whitespace intact when placing it into a design.

Logo sizing limits

Nimriz automatically increases the error-correction level when you add a logo, which provides some tolerance for the logo obscuring data modules. However, this tolerance is limited:

Keep your logo to no more than approximately 20–25% of the total QR area.
If the logo has a complex shape or dark background, add a white background plate behind it within the logo image before uploading.
If your code is failing to scan and you have a logo, try reducing the logo size as the first troubleshooting step.

Always test before publishing

Always scan your final downloaded QR code with a standard smartphone camera app before:

Printing on physical materials.
Including in a large-format design.
Publishing to a public audience.

Test on both iOS and Android. Test in multiple lighting conditions.

Troubleshooting

The QR code will not scan

Work through these steps in order:

Low contrast-check your color choices. If foreground and background are too similar, increase the contrast. A simple black-on-white version of the same code will always scan if the code data itself is valid.
Logo too large-remove the logo and test again. If the code scans without the logo, reduce the logo size or add a white plate behind it.
Quiet zone too small-increase the quiet zone setting in your QR editor and re-download.
Damaged or compressed image-if you downloaded a PNG and it was later compressed or resized by another tool, re-download at a higher resolution directly from Nimriz.
Printer color matching-some print processes shift colors unpredictably. Test a physical print before ordering a large run.

The downloaded file looks different from what I designed

QR assets are generated on demand and may be cached. If you recently made changes (updated colors, swapped a logo, changed the preset) and the download looks outdated:

Look for a Regenerate or Refresh action on the QR panel.
Clear your browser cache and re-download.

Gradient, frame, or shape customization options are not visible

These are plan-gated features. If you do not see gradient, frame, or shape options in the QR editor, your workspace plan does not include that level of QR customization. Contact your organization administrator or check your plan details.

The QR links to the wrong destination

The QR code is tied to your short link. If your short link's destination has been updated, the QR code will automatically point to the new destination-no redesign or re-download needed. If the QR is going to the wrong place, check the destination URL on the link itself in your dashboard.

QR API

Professional and Enterprise plans can automate QR rendering and QR preset management through the Nimriz customer API.

Authentication

Use the same workspace API key posture as the rest of the Nimriz customer API.
Send the key in the Authorization: Bearer <key> header.

Available endpoints

POST /api/v1/qr/generate
GET /api/v1/qr/presets
POST /api/v1/qr/presets
PUT /api/v1/qr/presets/:id
DELETE /api/v1/qr/presets/:id
GET /api/v1/links/:id/qr
GET /api/v1/links/:id/analytics?touch_type=qr_scan

Behavior

POST /api/v1/qr/generate renders a QR image for an existing url_id. You can request svg or png, control the size, force regeneration, and optionally provide a preset override or validated style override.
GET /api/v1/links/:id/qr returns the link's effective QR asset using the same deterministic rendering contract as the dashboard.
GET /api/v1/links/:id/analytics returns QR-filtered daily totals and time-series points when you set touch_type=qr_scan.
Preset CRUD uses the same strict style schema and frame entitlement rules as the dashboard.

Notes

The QR API does not bypass plan entitlements. If your workspace cannot use a frame template, custom frame text, or QR API access in the app, the same request is blocked at the API layer.
QR image generation remains deterministic for the same short URL and style input.