Issuing a passport

Quick reference

• Issue a passport from /passports/new — title, jewellery type, optional metal / stone / ring specifications, provenance, owner, visibility. The piece doesn't need an inventory record first; a passport describes the piece on its own terms.
• Every new passport gets two identifiers: a UUID v4 public_uid for the customer-facing /verify/[uid] route, and a global numeric identity number (starting at 100000001, shared across the whole platform) shown on the jeweller-side detail page and the printed certificate.
• Passports issue with visibility set to public by default — the QR code and /verify/[uid] URL resolve immediately. Flip the visibility toggle on the passport detail page to keep a passport private (still in your tenant, hidden from the public lookup).
• Photos are added on the detail page after the passport is saved — a primary image plus a gallery. The creation form collects everything except photos in one step.
• If you set current_owner_email at issuance, the owner receives a passport email automatically; you can resend it later from the detail page. If you didn't set an email, the customer can still reach the passport via QR sticker, printed certificate, or the receipt link.

Walkthrough

1. Open the new-passport form

From /passports tap Create Passport in the top right. The form at /passports/new is a single page split into sections: Piece Details, Metal, Stone (collapsible), Ring (auto-expands when jewellery_type is set to ring), Provenance, Ownership, Visibility. Most fields are optional — the only required input is the title.

2. Fill the piece details

The title is the customer-facing description that renders across the passport card, the printed certificate, and the aftercare email — “Oval Diamond Solitaire Ring” or “Vintage Sapphire Pendant 1962” rather than a SKU. Jewellery type drives which subsections matter (the Ring section auto-expands for rings; you can still open Stone manually on any type). The description field is free text — useful for the heritage of the piece or any wording you want to surface on the certificate.

3. Record the specifications

The Metal, Stone, and Ring cards mirror the vocabulary the customer-facing card renders — metal type / colour / purity / weight; stone type / shape / carat / colour / clarity / origin / certificate number; ring size / setting style. Fill in what you can verify; leave the rest blank. Empty fields don't render on the public passport card, so a sparse passport reads cleanly rather than as a page of missing labels.

The certificate number field is the place to reference an external grading report (e.g. GIA 1234567890) when one exists. Nexpura's passport doesn't replace gem-lab certification — it records the report you've already obtained so the customer (and any future buyer) can cross-reference.

4. Provenance and ownership

Provenance fields — maker / designer, made-in country (defaults to Australia, editable), year made — appear on the customer-facing card under their own subhead. These are the historical attribution fields that matter most for resale-grade pieces and heritage stock.

The Ownership block records the current owner of the piece — full name, email, purchase date, purchase price. Setting an email here triggers the passport email automatically once you save. You can leave the block blank if the piece hasn't sold yet (for inventory you want passport-ready before it leaves the case) and fill it in later from Edit Passport or via the transfer-ownership action documented on Transferring passport ownership.

5. Visibility — public or private

The visibility toggle defaults to public. Public means the QR-code URL and the /verify/[uid] lookup resolve immediately — anyone with the UID can read the public-facing passport card. Private keeps the passport inside your tenant; the public surface returns a branded-not-found card for the UID until you flip it back to public. Most retail passports stay public; private is for drafts, internal-only records, or passports temporarily taken off the public surface during a dispute or investigation.

6. Save — the system mints two identifiers

On save, Nexpura mints two identifiers for the passport:

• A UUID v4 public_uid — 122 bits of entropy, unenumerable, the canonical identifier for the public /verify/[uid] route. New QR codes encode this form. Customers see the UUID in the URL when they verify.
• A global numeric identity number — starts at 100000001, shared across the whole platform (not just your tenant). Shown on the jeweller-side detail page and on the printed certificate as the human-friendly reference, and still accepted as a lookup on /verify for legacy compatibility. Passports issued before mid-2026 used this number as the primary identifier; new passports use the UUID for the public route but the numeric one is still printed for at-a-glance recognition.

Older Nexpura passports may also carry an NXP-XXXXXX short-form identifier; that's legacy and not minted for new passports. All three forms resolve to the same passport on /verify today — the legacy formats are scheduled to sunset 2026-08-05.

7. Add photos on the detail page

After save, the form redirects to the passport detail page at /passports/[id]. The Photos card sits beneath the specifications — upload a primary image (renders large on the public card) plus a gallery of up to a handful of additional shots. The primary image is what the customer sees first when they land on /verify/[uid].

8. Hand the customer the UID

The detail page surfaces every channel the customer can arrive on the passport through:

• QR code. The right-hand QR Code card renders the printable QR for the piece. Download as PNG, print on a sticker (we use the trailing portion of the certificate or a hangtag), and the customer scans straight into the passport card.
• Printed certificate. The Download Certificate action generates a PDF with your business name, ABN, address, the piece details, and the verification block. Hand it with the piece at sale.
• Passport email. If you set an owner email, an email goes out automatically on creation with the passport link. If you set the email later or the customer asks for it again, use the Send Passport Email button on the detail page. (Channel: email — passport emails go via the email channel specifically; SMS / WhatsApp aren't wired for passport delivery.)
• View Public Page. The View Public Page link beneath the QR opens the customer-facing passport in a new tab so you can sanity- check what the customer will see before you hand the piece over.

9. Issuing retroactively for a piece sold years ago

A customer brings in a piece you sold before you ran Nexpura — they want a passport for resale or insurance. The flow is the same /passports/new form; you fill in everything you can reconstruct from your records (the take-in slip, the original receipt, a valuation), set the purchase date in the past, and save. The passport mints fresh identifiers regardless of when the piece itself was sold. The customer ends up with a passport card and a certificate as if the passport had always existed.

One thing the system doesn't do: there's no back-dated “issued” timestamp. The event timeline records the actual issuance date — the day you created the passport — rather than the original sale date. The original sale date lives in the purchase_date field on the Ownership block. If you want the public card to read the original sale date as the historical reference, set purchase_date correctly on creation; the card surfaces it under Ownership alongside the purchase price.

Common questions

Troubleshooting