Skip to main content
Sooner or later someone scans a code Closient doesn’t recognise. A typo in a print file, a product that was never added to your catalog, a label from a supplier, a counterfeit. None of these are rare, and each one tells you something. This page explains what Closient does with that scan, what you can choose to do instead, and exactly what information reaches the page you send the scanner to.

​
Every scan gets one outcome

Each scan of a product code ends in exactly one of six outcomes. The outcome is also the reason code you’ll see in reports and in redirect parameters. Only the four dead ends trigger your fallback policy. resolved and partial both put the scanner in front of a real page.
Today the outcome codes cover product (GTIN) scans. Other identifier types on the resolver, such as SSCC and GLN, are not classified this way yet.

​
Lot and serial walk-up

A scan can carry more than the product. A code such as /01/09506000134352/10/LOT9/21/SN42 names a product, a lot and a single unit. Closient looks for the most specific thing you’ve registered and works back from there:
  1. The serial number, if it’s registered.
  2. The lot, if it’s registered.
  3. The product.
If the scan carries a lot or serial you haven’t registered, Closient doesn’t fail. It walks up to the next level it does know, and the scanner lands on your product’s page (or wherever your product-level, brand-level or organization-level resolver rules point). That follows the GS1 Digital Link resolver standard: an unknown lot under a known product is not a missing product. A walk-up is recorded with the reason partial. It is not a dead end and it never triggers your fallback policy, but it is still worth knowing about. An unregistered lot or serial can mean a lot you forgot to register, or a code that shouldn’t exist.

​
The two fallback modes

The fallback policy is set per custom domain. It applies when a scan enters through a hostname you’ve connected, such as id.yourbrand.com. Scans that come in through Closient’s own domains always get the default behavior.

​
Hosted 404 (default)

Closient answers with a real HTTP 404, not a redirect. What the scanner sees depends on the reason: The page is marked noindex and is never cached, so it can’t leak one brand’s theming onto another visitor’s screen, and it stops appearing the moment you add the product.

​
Redirect

In redirect mode, every dead end is answered with a redirect to a page on your own site. It is opt-in, and you choose the destination.
  • Always a 307. Never 301 or 308. Browsers and CDNs cache permanent redirects, and a code that fails today may be a valid, registered product tomorrow. A 307 is never cached as a permanent answer.
  • The destination is yours alone. It is set in your configuration and never taken from anything in the scan, so nobody can craft a code that sends people somewhere else through your domain. It must be an absolute https:// URL.
  • UTM tags are added. The defaults are utm_source=closient, utm_medium=qr and utm_campaign=unresolved_scan. You can override any of the five UTM fields (utm_source, utm_medium, utm_campaign, utm_term, utm_content); a blank field keeps the default, and utm_term and utm_content are left out unless you set them.
  • Diagnostic parameters are added. These are the csi_ parameters described below, so your page can tell what failed and why.
  • Your own query parameters win. If your destination URL already has a parameter with the same name, it is kept and Closient’s version is not added.
Redirect mode covers people scanning with a phone or browser. A machine client that explicitly asks for a linkset or JSON representation of a known product keeps the standard 404 behaviour rather than being redirected.

​
The csi_ parameter reference

Every redirect carries diagnostic parameters that start with csi_. The prefix stands for Closient Search Inc. It is a namespace reserved for the platform, so it won’t collide with parameters your own site uses. Don’t use csi_ names for your own tracking. Nothing is passed through as-is. Each value is checked before it is included, length-capped (14 characters for the GTIN, 20 for a lot or serial, 256 for the path), and URL-encoded. A value that fails its check is left out rather than cleaned up, so a garbled scan can never put arbitrary text into your URL. For a malformed scan the bad value is the whole problem, so csi_gtin and csi_path (which contains it) are never sent. For an unknown product scanned on id.yourbrand.com with a redirect destination of https://yourbrand.com/not-found, your page receives something like this (parameter order isn’t guaranteed):
Treat these values as information, not instructions. They come from a code someone scanned, so validate and escape them if your page displays them.

​
Setting your policy

You set the policy per hostname with the custom hostname API, using an account with change permission on your organization:
Send the hostname, the mode (hosted_404 or redirect), and for redirect mode the redirect_url and any UTM overrides. If the mode is redirect and the URL isn’t a well-formed absolute https:// URL, the request is rejected with a 422 and nothing changes. See API overview for authentication. There is no settings page for this yet. Until there is, the API is the way to change it.

​
See what people are scanning

Every dead end and every partial walk-up on your custom domains is recorded, on every plan. Reading that record is a Business plan feature: the Unresolved scans page under Resolver lists each key with its reason, the domain it came in on, when it was first and last seen, and how many times it was scanned. For an unknown_key you can create the product in one click, prefilled with the scanned GTIN. Read it as a to-do list. A GTIN that keeps showing up as unknown_key is a product missing from your catalog. A one-off invalid_checksum is a typo. A GTIN that no one at your company recognises may be a counterfeit.

Setting up resolver rules

Choose where a successful scan goes, by product, lot, serial or time.

QR code sizing

The length of your resolver domain decides how big your printed QR code has to be.