Module

Passports

A Digital Product Passport (DPP) in PassportBox is the structured record that captures a product's material composition, supply chain provenance, environmental data, and compliance information. Once published, it becomes a consumer-accessible document linked to a GS1 Digital Link and a public URL.

Purpose

Passports are the primary output of PassportBox. They fulfil product-transparency obligations (such as the EU Digital Product Passport regulation), give consumers verifiable sustainability information at the point of scan, and provide brands with an auditable record of product data. Every passport is anchored to a product record and optionally enriched with supplier, materials, and carbon data.

When to Use

—New product launch. Create a passport before or alongside the physical product launch so the GS1 link can be printed on packaging.
—Regulatory compliance. Use passports to meet DPP mandates by capturing all required material, supplier, and carbon data in a structured, machine-readable form.
—Supply chain updates. When a supplier or material composition changes, edit and re-publish the existing passport rather than creating a new one.
—End-of-life product retirement. Archive passports for discontinued products to preserve audit history without cluttering active views.

Prerequisites

Required: At least one product record must exist before you can create a passport. A passport must always be linked to a product. If you have not added products yet, go to Products first.

Recommended: Add your supplier(s) before creating passports. Linking a supplier is not required to save a DRAFT but is required for the passport to meet the full compliance score threshold and for publishing to be meaningful.

Creating a Passport

1.
Open the Passports list
Navigate to /dashboard/passports via the left sidebar. You will see any existing passports with their status badges.
2.
Click "New Passport"
The button is in the top-right corner of the list page. It navigates to /dashboard/passports/new.
3.
Enter the passport name
Choose a clear, human-readable name. This is used internally and displayed on the public passport view. Example: Recycled Wool Jacket — Spring 2025.
4.
Select a product
Use the product selector to link this passport to an existing product. This is a required field. Each product can have multiple passports over time (e.g. different batches or seasonal variants).
5.
Fill in the material and sustainability fields
Complete materials composition, recycled content percentage, carbon footprint, and recyclability. These drive the compliance score. More detail means a higher score and a richer public view.
6.
Link a supplier
Select the manufacturer or supplier from the dropdown. If the supplier has not been added yet, save the passport as DRAFT and add the supplier first, then return to complete this step.
7.
Save as DRAFT
Click Save. The passport is created with status DRAFT. You can return to edit it any time before publishing. No public URL is generated yet.

Editing a Passport

You can edit a passport in DRAFT status freely at any time. For PUBLISHED passports, edits are saved immediately to the internal record but the public view will not reflect changes until you re-publish.

1.Open the passport from the list or the Dashboard recent list.
2.The passport detail page loads at /dashboard/passports/[id].
3.Edit any field directly in the form.
4.Click Save to persist changes. Status remains unchanged.
5.If the passport was PUBLISHED, click "Re-publish" to push changes to the public view and update the GS1 Digital Link record.

Changing the linked product on a published passport will invalidate the existing GS1 slug. A new slug may be generated on re-publish. Update any printed labels accordingly.

Publishing a Passport

Publishing transitions a passport from DRAFT to PUBLISHED and makes it publicly accessible.

1.Open the passport at /dashboard/passports/[id].
2.Ensure all required fields are complete. The form will highlight missing required fields if you attempt to publish prematurely.
3.Click the "Publish" button in the top-right action bar.
4.PassportBox generates a unique public URL slug and a GS1 Digital Link.
5.The status badge changes from DRAFT (yellow) to PUBLISHED (green).
6.The public view is immediately live at /p/[slug].

After publishing, both a GS1 Digital Link and a label-ready QR code become available from the passport detail page. Only published passports can have labels generated.

Archiving a Passport

Archiving retires a passport without deleting it. Use this when a product is discontinued or when a passport is superseded by a newer version.

1.Open the passport at /dashboard/passports/[id].
2.Click the "Archive" option in the action menu (three-dot menu or Archive button depending on current status).
3.Confirm the action in the dialog.
4.The status changes to ARCHIVED (gray badge).
5.The public URL now displays an archived notice instead of the passport data.
6.Historical scan data is retained and visible in Analytics.

Archiving cannot be undone from the UI. Contact support if you need to restore an archived passport. DRAFT passports can be archived directly without publishing first.

Inputs and Fields Reference

Field	Type	Required	Description
Name	String	Yes	Human-readable label for the passport. Shown in list views and on the public page.
Product	Relation	Yes	The product this passport describes. Must exist before creating the passport.
Materials	Structured list	No	List of material components with name and percentage by weight. Drives compliance score.
Manufacturer	String	No	Name of the entity that manufactured the product. Can differ from the supplier.
Supplier	Relation	No*	Linked supplier record. Recommended for compliance score. *Required to reach full compliance threshold.
Carbon Footprint	Number (kg CO₂e)	No	Estimated or measured cradle-to-gate carbon footprint in kilograms of CO₂ equivalent.
Recycled Content	Number (%)	No	Percentage of the product's total weight made from recycled input materials.
Recyclability	Enum / text	No	Recyclability classification or instructions. Displayed prominently on the public view.
Compliance Data	Structured	No	Regulatory certifications, standards, or declarations attached to this passport.

Passport Statuses

DRAFT

Initial state after creation. The passport is private to your organisation. All fields are editable. No GS1 link or public URL has been generated. DRAFT passports do not count toward scan totals and are excluded from the Published metric on the Dashboard. Labels cannot be generated from a DRAFT.

PUBLISHED

The passport is live and publicly accessible. A GS1 Digital Link (https://id.gs1.org/...) and a public URL (/p/[slug]) are active. Scans are tracked. Edits require re-publishing to update the public view. Label generation is available.

ARCHIVED

The passport has been retired. The public URL shows an archived notice. The record is read-only and retained for compliance history. Existing scan data is preserved. Archived passports are excluded from the compliance score calculation and cannot receive new scan events.

The lifecycle is linear: DRAFT → PUBLISHED → ARCHIVED. You cannot move a passport from ARCHIVED back to PUBLISHED or DRAFT through the UI.

GS1 Digital Link

A GS1 Digital Link is a standardised URL format defined by GS1 that encodes a product identifier (such as a GTIN) and resolves to one or more digital endpoints — in this case, your published passport.

Format

GS1 Digital Links generated by PassportBox follow the pattern:

https://id.gs1.org/01/[GTIN]/

When it is generated

The GS1 Digital Link is generated at the moment a passport transitions from DRAFT to PUBLISHED. It is not available while the passport is in DRAFT status.

Where to find it

After publishing, the GS1 Digital Link appears on the passport detail page alongside a QR code ready for printing on labels. Copy it from there to embed in product packaging, labelling systems, or ERP records.

Public Passport View

The public passport view is the consumer-facing page at /p/[slug]. It is accessible to anyone with the link — no account is required.

What consumers see

—Product name, brand, and basic product description
—Materials composition breakdown
—Carbon footprint value (if provided)
—Recycled content percentage (if provided)
—Recyclability instructions
—Supplier name and country (if linked and set to public)
—Compliance certifications and declarations
—Last updated date

URL slug

The slug is automatically generated from the passport name and product identifier at publish time. It is stable — changing the passport name after publishing does not change the slug. You can share or print the /p/[slug] URL safely and it will remain valid for the life of the passport.

Validation Rules and Edge Cases

—Product is required to save. Attempting to save without a linked product will return a validation error.
—Material percentages must sum to 100%. If you enter material components, their percentages by weight must total exactly 100. The form will warn you if they do not.
—Recycled content cannot exceed 100%. Values above 100 are rejected.
—Carbon footprint must be a positive number. Negative values are not accepted.
—One active passport per product slug. If two passports for the same product are published, the most recently published one takes precedence for GS1 resolution. The older one remains published and accessible via its direct /p/[slug] URL.
—Filtering and search. The passports list at /dashboard/passports supports filtering by status (ALL, DRAFT, PUBLISHED, ARCHIVED) and free-text search by passport name or linked product name. Filters are applied client-side and do not require a page reload.
—API access. Passports are accessible via the REST API: GET /passports, POST /passports, PUT /passports/:id, POST /passports/:id/publish. API access requires a valid API key.

What Success Looks Like

The passport shows a green PUBLISHED badge and the detail page displays both a GS1 Digital Link and a QR code.

All required fields and recommended fields (supplier, materials, carbon footprint) are populated.

The public view at /p/[slug] renders correctly and all sustainability data is visible to consumers.

The Dashboard compliance score increases after publishing, reflecting that this passport meets the completeness threshold.

Scan events begin appearing in Analytics after the QR code is printed on labels and distributed.

Troubleshooting

Cannot publish — validation errors shown

The form highlights required fields in red before publishing. The most common missing items are: linked product (always required) and passport name. Fill in all highlighted fields and try again. If the error persists after filling all fields, check that material percentages sum to exactly 100%.

GS1 Digital Link is not appearing after publishing

Refresh the passport detail page. GS1 link generation is asynchronous and can take a few seconds. If the link still does not appear after 30 seconds, check that the linked product has a valid GTIN entered. A GS1 Digital Link cannot be generated without a GTIN.

Public view at /p/[slug] shows "not found"

This can happen if you are using a URL from before the passport was published, or if the passport has been archived. Confirm the passport status in your dashboard. If it is PUBLISHED, copy the URL directly from the passport detail page to ensure you have the correct slug.

Edits are not showing on the public view

Saving a published passport stores changes internally but does not automatically update the public view. You must click "Re-publish" after editing a published passport to push changes to the public URL and GS1 resolution endpoint.

Label generation button is greyed out

Label generation is only available for passports with PUBLISHED status. If the passport is in DRAFT or ARCHIVED state, the label button is disabled. Publish the passport first, then return to the detail page to generate labels.