DataFirefly Digital Product Passport — Documentation

Introduction

The DataFirefly Digital Product Passport plugin adds to WooCommerce everything needed to generate a Digital Product Passport (DPP) compliant with the European Ecodesign for Sustainable Products Regulation (ESPR). This passport will progressively become mandatory in the European Union from 2027, starting with textiles, batteries and consumer electronics, before extending to virtually every product placed on the European market.

Concretely, each WooCommerce product gains a stable unique identifier (UUID v4), a native QR code, a clean public URL like /dpp/{uuid}, a complete registry of components and materials, a traceability timeline, and a public REST API. No external calls: everything is generated server-side.

Requirements

• WordPress 6.0 or higher
• WooCommerce 7.0 or higher, activated
• PHP 7.4 minimum (tested up to PHP 8.3)
• A permalink other than “Simple” (Settings → Permalinks)

Installation

1. Download the dfdpp-1.0.0.zip file from your DataFirefly account.
2. Go to Plugins → Add New → Upload Plugin, select the ZIP, then Install Now.
3. Click Activate. The 5 custom tables are created automatically (wp_dfdpp_passports, wp_dfdpp_components, wp_dfdpp_materials, wp_dfdpp_suppliers, wp_dfdpp_events) and default options are set.
4. If the public URL /dpp/{uuid} doesn’t respond immediately, go to Settings → Permalinks and click Save Changes (without changing anything) to force a flush.

Global configuration

Go to WooCommerce → Passport DPP. This screen groups all plugin settings.

Public URL and QR Code

• URL prefix: default dpp, giving yourdomain.com/dpp/{uuid}. Change it if you prefer passport, product-passport or other. Remember to visit Settings → Permalinks after changing.
• QR size: zoom factor 1 to 10. Value 6 (default) produces about 240 px per side.
• Margin: number of white modules around the QR (4 by default).
• Error correction: L / M / Q / H. Stay on H if the QR will be printed on a label: up to 30% of the code can be damaged without compromising readability.
• Preferred format: PNG (raster, universal) or SVG (vector, better for large-format printing).

Default manufacturer identity

Fill in here the information you don’t want to retype product by product:

• Business name, address, country of manufacture
• Default country applied to components and materials
• Default ESPR category (textile, battery, electronics, furniture, etc.)

Public display

Five independent toggles control what your customers see on the public passport page:

• Carbon footprint (enabled by default)
• Suppliers (disabled by default — sensitive data)
• Material composition (enabled)
• Repairability and spare parts (enabled)
• Traceability timeline (enabled)

Automatic publication

If you check this option, each passport is automatically switched to published when the WooCommerce product itself is published. Useful for a catalogue of hundreds of products managed by a non-technical team. Otherwise, each passport must be published manually — which guarantees a final review.

Branding

• Accent colour: hexadecimal format (e.g. #0f172a). Applied to the hero, titles and buttons of the public page.
• Logo URL: displayed at the top of the public page. Use a transparent image (PNG or SVG) — it will be inverted on the dark background.

Creating a passport for a product

Open any product in WooCommerce. A new Passport DPP tab appears in the product data panel (next to General, Inventory, Shipping, etc.). It groups 8 sections.

Identification tab

The mandatory entry point for publication:

• Status: Draft / Published / Archived. Only Published makes the public URL accessible.
• ESPR category: determines the data structure European auditors will expect to find. Choose textile, battery, electronics, furniture, iron_steel, aluminium, tyres, detergents, paints, lubricants, chemicals, cosmetics, toys, construction or general.
• GTIN / EAN / UPC: international commercial barcode.
• Model reference, Batch number, Serial number: fill in the fields applicable to your product.
• Manufacturer: name, address, country (pre-filled from global settings if configured).
• Manufacturing date and Manufacturing site (city, factory or workshop).

Sustainability and footprint tab

• Carbon footprint: numerical value, unit (kgCO2e by default) and reference calculation methodology (PEF, ISO 14067, GHG Protocol). Only fill in the footprint if you can justify it with a documented methodology — it’s the most scrutinised point in audits.
• Repairability index: score out of 10.
• Expected lifespan in years.
• Warranty duration in months (EU obligation of at least 24 months for consumer goods).
• Spare parts availability in years.
• Recycled content as percentage.
• Recyclable content as percentage.

Instructions tab

Four rich fields accepting basic HTML (paragraphs, lists, links):

• Usage: advice to get the most out of the product and extend its lifespan.
• Care: washing, drying, storage.
• Recycling: recycling stream, selective sorting, collection points.
• End of life: what to do when the product is no longer usable.

Compliance tab

• Substances of concern (SCIP / REACH): list of substances from the REACH candidate list present at more than 0.1% by weight. Free format; we recommend a bullet list with name and CAS number.
• Hazardous materials: mention of applicable hazard classes (CLP, GHS).
• Certifications and labels: OEKO-TEX, GOTS, GRS, Ecolabel, EPEAT, etc.

Components tab

Flat registry of components that make up the product. For each component, you add:

• Name (required)
• Type: from a predefined list (main fabric, lining, sole, buckle, zipper, etc.)
• Weight in grams
• Supplier name (never exposed publicly unless you enable the dedicated toggle)
• Country of origin in 3-character ISO 3166 alpha-3 (e.g. FRA, ITA, CHN)
• Recyclable: yes / no
• Replaceable: yes / no (relevant for electronics, furniture)

Materials tab

More granular material registry with standardised codes:

• Material code: dropdown with the main ISO 11469 / ISO 1043 codes for plastics (PET, PP, PE, PVC, PS, PA, etc.), ISO 1833 for textiles (WO wool, CO cotton, PL polyester, VI viscose, EL elastane, etc.), DIN 6120 for metals, and battery chemistries (Li-ion, LFP, NMC, NCA, NiMH, Pb).
• Custom name: if the predefined code doesn’t fit.
• Percentage: share of this material in the product (up to 4 decimals).
• Recycled + % recycled: whether it’s recycled content, and if so at what proportion.
• Renewable: material of renewable biological origin.
• CAS number: CAS identifier of the substance (for regulated chemical substances).

Traceability tab

Timeline of key lifecycle events. Each event associates a date, type, actor, location and description. Available types cover the full cycle:

• Production
• Quality control
• Transport
• Import / Export
• Distribution
• Sale
• Repair
• Refurbishment
• Recycling
• End of life

QR Code tab

This tab becomes active as soon as the product is saved for the first time. It displays:

• The generated QR code (data-URI preview)
• The passport UUID
• The clickable public URL
• Three download buttons: PNG, SVG and raw JSON

Publishing a passport

A passport in Draft status is not publicly accessible — the URL returns a 404. To publish it:

1. Open the product, go to the Passport DPP → Identification tab.
2. Switch Status to Published.
3. Click Update at the top right of the product.

The first publication date is automatically stored in published_at. A published passport can be reverted to Draft or moved to Archived at any time.

Public passport page

The URL of the form yourdomain.com/dpp/8f3a2c1d-4b5e-6f7a-8b9c-0d1e2f3a4b5c opens a responsive page with:

• A hero with the product name, ESPR category, brand logo and product image
• An identifiers banner (UUID, GTIN, model, batch, serial, SKU)
• A manufacturer card with address and production date
• A sustainability and footprint card with metrics as tiles
• The components and materials tables (depending on display toggles)
• The instructions (usage, care, recycling, end of life)
• The regulatory compliance (certifications, substances, hazardous materials)
• A vertical traceability timeline with dates and locations
• A QR code sidebar with PNG / SVG / JSON download
• A schema.org Product JSON-LD block automatically injected for SEO and interoperability

On the public WooCommerce product page, a discreet block invites visitors to view the passport, with a miniature QR. This block is added automatically below the product summary (hook woocommerce_after_single_product_summary, priority 25).

Alternative formats

The same URL accepts two suffixes:

• /dpp/{uuid}?dfdpp_format=json or /dpp/{uuid}.json: returns the full JSON payload, including the JSON-LD block.
• /dpp/{uuid}?dfdpp_format=qr or /dpp/{uuid}/qr: directly downloads the QR code PNG.

REST API

All endpoints are exposed under the dfdpp/v1 namespace.

Public endpoints

• GET /wp-json/dfdpp/v1/passport/{uuid} — returns the full JSON payload of the passport.
• GET /wp-json/dfdpp/v1/passport/by-product/{product_id} — same but searched by WooCommerce product identifier.
• GET /wp-json/dfdpp/v1/passport/{uuid}/qr — returns the QR code as vector SVG.

These endpoints only return passports in Published status.

Authenticated endpoints

Require Application Password or OAuth authentication and a capability of manage_woocommerce or edit_products:

• PATCH /wp-json/dfdpp/v1/passport/{product_id} — partially updates the fields of a passport.
• POST /wp-json/dfdpp/v1/passport/{product_id}/publish — publishes the passport (shortcut without going through admin).

Customisation

Override the public page

Copy public/templates/dpp-public.php from the plugin to a dfdpp/ folder at the root of your active theme. The plugin will use this file preferentially, allowing you to completely rework the rendering without touching the plugin. Data retrieval logic remains unchanged: you have $passport and $data variables exactly as in the original template.

JSON payload filter

The dfdpp_passport_payload filter lets you add or modify fields in the exposed JSON payload. Example: add a proprietary internal_reference field visible only to your ERP.

add_filter( 'dfdpp_passport_payload', function ( $data, $passport ) {
    $data['custom'] = array(
        'internal_reference' => get_post_meta( $passport->product_id, '_erp_ref', true ),
    );
    return $data;
}, 10, 2 );

Block on the product page

The block inviting to view the passport on the public WooCommerce product page can be moved, disabled or replaced by manipulating the hook:

// Remove completely
remove_action( 'woocommerce_after_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

// Place elsewhere, e.g. above the Add to cart button
add_action( 'woocommerce_single_product_summary', array( dfdpp()->frontend, 'render_product_dpp_link' ), 25 );

Translations

The plugin ships with a complete French translation (languages/dfdpp-fr_FR.po and .mo) and a template file dfdpp.pot (291 unique strings) to translate into other languages using Poedit or any gettext-compatible tool.

Polylang Pro and WPML are supported for translating product content (name, description, ESPR category). The passport remains attached to the source product, guaranteeing a single source of truth for compliance data while allowing multilingual display of the public page.

HPOS compatibility

The plugin explicitly declares its compatibility with WooCommerce’s High-Performance Order Storage. It stores no data in the shop_order custom post type — the 5 dedicated tables are independent. You can activate HPOS without fear of breaking the plugin.

FAQ and troubleshooting

The public URL returns a 404

Three possible causes:

• The passport is in Draft or Archived status — switch it to Published.
• Rewrite rules haven’t been flushed — go to Settings → Permalinks and save (without changing anything).
• A “Simple” permalink is active — switch to “Post name” or any non-simple format.

The QR code doesn’t display

Check that your host allows writing to the wp-content/uploads/ directory and that the GD PHP extension is enabled (required for PNG generation). If you’re in a constrained environment, force SVG format in settings: it doesn’t depend on GD.

How to provide traceability to an external partner?

Use the REST API. Create a dedicated Application Password for the partner in their WordPress user account (Users → Profile → Application Passwords), then provide them with documentation of a PATCH endpoint so they can push their own traceability events over time.

Can I generate QR codes in bulk?

Yes, via WP-CLI. A custom script can loop over products and call DFDPP_QRCode::output_png() or ::as_svg() to generate the files. Contact support if you want a turnkey WP-CLI command for your catalogue.

Does it work with variable products?

Yes, the passport is attached to the parent product. If you need a distinct passport per variation (typical for electronics where each configuration has a different carbon footprint), contact us to discuss an extension.

Uninstallation

Simple deactivation of the plugin preserves all data. Your passports remain in the database, ready to be reactivated.

Complete uninstallation (Delete button on the plugins page) triggers uninstall.php, which:

• Removes the 5 custom tables
• Removes all dfdpp_* options
• Cleans up any transients
• Flushes rewrite rules

Support

Technical support is provided by email in French and English. Write to support@datafirefly.com specifying the plugin version, WordPress and WooCommerce versions, and an extract of the logs if you have a PHP error message.