Branded QR codes

After this page, every QR code your workspace makes carries your colours and app icon, and your server can fetch a print-ready code for any link.

On this page 7
  1. 1. Set your workspace's QR style
  2. 2. Download a code from the dashboard
  3. 3. Make codes from your server
  4. 4. Saved styles, and a whole campaign at once
  5. 5. Check scans in Analytics
  6. Common errors
  7. Next steps
Time
About 10 minutes
You need
A link to print. For the app icon, an icon set in Settings → How your link pages look. For the API, a secret key.
Works on
Dashboard, or any server (curl, Node, Python, PHP, Java, Go)

A QR code is the link drawn as squares. Strait draws every code from one workspace style, so a code you download from the dashboard and one your server makes through the API look the same. Scans count as the qr channel in Analytics unless you turn that off.

1. Set your workspace's QR style

Open Dashboard → Settings → QR codes and choose:

  • Code colour: the squares. Empty means black.
  • Background: behind the squares. Empty means white.
  • Put my app icon in the middle: uses the app icon from How your link pages look. The code then uses the highest error correction level (H), so it still scans with the middle covered.

The colours must pass one rule: the code must be darker than its background, with a contrast of at least 3:1. Phone cameras look for dark squares on a light background, so light-on-dark codes and pale colour pairs are refused, in the dashboard and in the API. The form shows the contrast as you type. Then press Save QR style. Owners, admins and members can change it; viewers can only look.

You should see: the preview in your colours, a line under the colour fields like "Contrast 21.0:1: phone cameras will read it", and "Saved ✓" after you save.

2. Download a code from the dashboard

Go to Dashboard → Links and press QR on any link. The dialog shows the code in your style and the exact URL it opens. Keep Count scans as the qr channel in Analytics ticked to add utm_source=qr to the code, then pick a download:

Button You get
Download PNG 1024 × 1024 px, for screens and documents
PNG for print 2048 × 2048 px
Download SVG Vector, sharp at any print size

You should see: a file named after the link in your downloads (summer-qr.png, summer-qr-2048.png or summer-qr.svg), and the code opening the link when you scan it with a phone.

3. Make codes from your server

Call GET /v1/links/{slug}/qr with a secret key. It answers with the image itself, in the workspace style unless you override it for this one code:

Query parameter Values Default
format png or svg png
size 128 to 2048 px 1024
margin 0 to 16 modules of quiet zone 2
color, background hex, like 1f2937 the workspace style
logo true or false the workspace style
track true adds utm_source=qr true
Terminal
curl "https://strait.link/v1/links/summer/qr?format=svg&color=1f2937" \
  -H "Authorization: Bearer $SECRET_KEY" \
  --fail -o summer-qr.svg
Node 18+
import { writeFile } from 'node:fs/promises';

const res = await fetch('https://strait.link/v1/links/summer/qr?format=png&size=2048', {
  headers: { Authorization: `Bearer ${process.env.SECRET_KEY}` },
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
await writeFile('summer-qr.png', Buffer.from(await res.arrayBuffer()));
console.log(res.headers.get('x-strait-qr-url'), res.headers.get('x-strait-qr-logo'));

Two response headers tell you what you got: X-Strait-Qr-Url is the exact URL in the code, and X-Strait-Qr-Logo says whether the icon went in (embedded, off, no_icon, unavailable or png_needs_png_icon). Python, PHP, Java and Go versions are on the endpoint page. Write the colours without #, or as %23 (a raw # starts the URL's fragment).

You should see: summer-qr.svg on disk, and X-Strait-Qr-Url: https://hilltop.strait.link/summer?utm_source=qr.

4. Saved styles, and a whole campaign at once

For a second look (packaging in brand colours, a black-and-white flyer), save it as a style. In Dashboard → Settings → QR codes, set the colours, then under Saved styles type a name and press Save as a style. A workspace keeps up to 12, and each one passes the same 3:1 contrast rule. Pick a style in the QR dialog, or pass its id as preset to the API; color, background and logo still override it.

To print every link of a campaign, filter Dashboard → Links by the campaign and press QR ZIP for this campaign. From a server, call GET /v1/qr.zip: one code per live link, named <slug>-qr.svg (or .png), sorted by slug. GET /v1/workspace lists your saved styles (qrStyles) with their ids.

Terminal
curl "https://strait.link/v1/qr.zip?campaign=diwali_sale&preset=p-packaging" \
  -H "Authorization: Bearer $SECRET_KEY" \
  --fail -o diwali-sale-qr-codes.zip

A ZIP holds up to 500 SVG codes, or 50 PNG codes at up to 1024 px; a workspace can make 3 ZIPs a minute. Your AI tool can do the same with the MCP server (get_campaign_qr_zip).

You should see: diwali-sale-qr-codes.zip on disk, and X-Strait-Qr-Count in the response saying how many codes it holds.

5. Check scans in Analytics

Scan a downloaded code with a phone, then open Dashboard → Analytics.

You should see: the tap under the qr channel, with where it went (app, store or website), like any other tap.

Common errors

  • 400 "the QR colours are too close to scan reliably" or "the QR colour must be darker than its background". The code must be darker than its background with a contrast of 3:1 or more (light-on-dark codes are refused because many phone cameras miss them). Darken the code, lighten the background or swap them; plain black on white is always fine.
  • 400 "unknown preset", or 404 from /v1/qr.zip. The style id doesn't exist (GET /v1/workspace lists the ids), or no live link has that campaign (check the spelling in Dashboard → Links; paused links are left out).
  • X-Strait-Qr-Logo: png_needs_png_icon. Your app icon is a JPEG or WebP, and PNG codes can only embed a PNG icon. Ask for format=svg, or upload a PNG icon in Settings.

Next steps