# TrueTag

> TrueTag is a Shopify app that gives each product a unique serial number and QR code at fulfilment. Scanning the code opens a verify page showing whether the store that sold the item issued that code.

TrueTag does not rate sellers or judge product quality. A result only tells you whether a code was issued by the store that uses TrueTag, and whether that store still stands behind it.

## Verify URLs

A TrueTag code links to a page of the form:

https://truetag-rho.vercel.app/v/{token}

`{token}` is 1-64 characters of A-Z, a-z, 0-9, `_` or `-`.

Tokens are case-sensitive: use the URL exactly as scanned, without changing its letter case.

## Checking a code (for agents)

Send a GET request to:

https://truetag-rho.vercel.app/api/verify/{token}

No key is needed. The response is JSON: `{ "success": true, "data": { ... }, "error": null, "meta": { ... } }`.

`data` fields:
- `result`: one of `genuine`, `void`, `unknown`, `test` (below)
- `meaning`: one plain-English sentence describing the result
- `serial`: the serial number on the label, or null
- `product`: `{ "title": ... }`, or null
- `brand`: the store's display name as shown on the verify page, or null
- `issued_at`: when the unit was issued (ISO 8601), or null
- `warranty`: `{ "status": "active" | "pending" | "expired" | "void" | "none", "expires_at": ISO 8601 or null }`
- `verify_url`: the human verify page for this code

The verify page also carries the same answer as schema.org JSON-LD, and links to this endpoint with `<link rel="alternate" type="application/json">`.

## What each result means

- `genuine`: the code was issued by the store that sold this product, and the store still lists the item as active.
- `void`: the code was issued by the store, but the store has since voided it (for example after a refund or return), so it no longer vouches for this item.
- `unknown`: the code was not issued by any store using TrueTag. It may be mistyped, or the label may not be genuine.
- `test`: a test code from a developer sandbox. It does not belong to any real product.

## Errors

- 400 `invalid_token`: the token is not in the format above.
- 429 `rate_limited`: more than 60 requests a minute from one IP. Wait a minute and retry.
- 503 `temporarily_unavailable`: the lookup failed. Retry later. This never means the product is fake.

## Privacy

No buyer data is ever exposed: no names, emails, addresses, order numbers or registration details. The endpoint is read-only and does not record your request as a scan.