Materials and composition

Materials and composition data is essential for transparency in digital product passports. Avelero helps you build a centralized material catalog and assign accurate composition percentages to products and variants.

Material catalog

Your brand’s material catalog is a centralized repository of all materials used across your products. Materials are created once and reused across your entire catalog.

Creating materials

Each material in your catalog includes:

Name: Material identifier (e.g., “Organic Cotton”, “Recycled Polyester”)
Country of origin: Where the material is sourced
Certification: Optional link to a material certification
Recyclable status: Whether the material can be recycled

Navigate to materials settings

Go to Settings → Materials to access your material catalog

Add a new material

Click Add material and enter the material name and properties

Link certification (optional)

Associate a certification from your certification catalog if applicable

Use in products

The material is now available for assignment to any product or variant

Materials are scoped to your brand. Each brand maintains its own material catalog, so materials can be customized to match your specific sourcing and naming conventions.

Material certifications

Certifications validate material claims and provide transparency to consumers. Each certification includes:

Title: Certification name (e.g., “GOTS Organic”, “OEKO-TEX Standard 100”)
Certification code: Unique identifier or certificate number
Institute details: Certifying organization name, email, website, and address
Issue and expiry dates: Validity period of the certification
Certificate document: Upload path for the certification file

Setting up certifications

Create a certification:

Go to Settings → Certifications
Add certification details including institute information
Upload the certificate document
Set issue and expiry dates

Link to materials:When creating or editing a material, select the appropriate certification from your catalog. One certification can be linked to multiple materials.

Certification data structure

Certifications store comprehensive institute details:

{
  title: "GOTS Organic Certification",
  certificationCode: "GOTS-2024-12345",
  instituteName: "Control Union",
  instituteEmail: "info@controlunion.com",
  instituteWebsite: "https://controlunion.com",
  instituteAddressLine1: "Meeuwenlaan 100",
  instituteCity: "Amsterdam",
  instituteCountryCode: "NL",
  issueDate: "2024-01-15",
  expiryDate: "2025-01-15",
  certificationPath: "/uploads/certs/gots-cert.pdf"
}

All fields are optional except the title, allowing flexibility for different certification types.

Product composition

Composition defines what materials make up a product and in what percentages. You can define composition at either the product or variant level.

Product-level composition

Set material composition that applies to all variants of a product:

Open the product editor

Navigate to the product and open the Materials section

Add materials

Click Add material to add a row to the composition table

Select material and percentage

Choose a material from your catalog and enter the percentage (0-100)

Add additional materials

Continue adding materials until the composition is complete

The materials table shows:

Material name: Selected from your material catalog
Country of origin: Automatically displayed from the material’s data
Percentage: Composition percentage for this material
Total: Running total to help you reach 100%

Percentages should total 100% for complete composition data. Avelero displays a warning if the total exceeds 100% but doesn’t prevent saving.

Variant-level composition

Variants can override product-level composition when materials differ between variants:

Product: "Summer Dress"
├─ Product materials: 60% Cotton, 40% Linen
├─ Variant: "Blue - Small"
│  └─ Inherits: 60% Cotton, 40% Linen
└─ Variant: "Red - Small"
   └─ Override: 70% Organic Cotton, 30% Recycled Polyester

Important: Variant materials completely replace product materials—they don’t merge. If you add any materials to a variant, the product’s materials are ignored for that variant’s digital passport.

Adding materials in the product form

The materials section in the product editor provides an interactive table interface:

Material selection

Click in the Material column to open a searchable dropdown
Search existing materials by name
Create new materials inline by typing a name not in the catalog
Each material can only be added once per product

Creating materials inline

When you type a material name that doesn’t exist:

A Create “Material Name” option appears in the dropdown
Click to open the material creation sheet
Fill in material properties (country of origin, certification, recyclable)
Save to add the material to your catalog and assign it to the product
The percentage you entered is preserved

This workflow lets you build your material catalog without leaving the product editor.

Percentage entry

Enter percentages as decimal numbers (e.g., 33.5 for 33.5%)
The percentage column shows a % symbol prefix
Empty percentages are stored as 0
Total is calculated and displayed at the bottom
Totals over 100% are highlighted in red

Country display

Country of origin is automatically populated from the material’s data:

Displays as a tag with the full country name
Derived from the material’s countryOfOrigin field
Cannot be edited per-product (edit the material in the catalog instead)

Data validation

Material composition data has specific validation rules:

Material uniqueness

Each material can only appear once in a product’s composition:

Enforced at the database level via unique constraint
The UI prevents selecting already-added materials
Prevents duplicate materials in the composition table

Material deletion restrictions

Materials in use cannot be deleted from the catalog:

Database enforces RESTRICT on delete
You must remove the material from all products first
Prevents orphaned material references

Percentage precision

Percentages are stored with high precision:

percentage: numeric({ precision: 6, scale: 2 })
// Supports values like 33.33, 12.50, 0.01

This allows accurate composition data down to hundredths of a percent.

Material data structure

Understanding the underlying data model helps you use materials effectively:

Brand materials table

{
  id: "uuid",
  brandId: "uuid",
  name: "Organic Cotton",
  certificationId: "uuid | null",
  recyclable: true,
  countryOfOrigin: "IN",
  createdAt: "timestamp",
  updatedAt: "timestamp"
}

Product materials table

{
  id: "uuid",
  productId: "uuid",
  brandMaterialId: "uuid",
  percentage: 65.00,
  createdAt: "timestamp",
  updatedAt: "timestamp"
}

Variant materials table

{
  id: "uuid",
  variantId: "uuid",
  brandMaterialId: "uuid",
  percentage: 70.50,
  sourceIntegration: "shopify | null",
  sourceExternalId: "external-id | null",
  createdAt: "timestamp"
}

Variant materials include source tracking fields to maintain data lineage when syncing with external systems.

Best practices

Build your catalog first

Create commonly used materials in your catalog before adding products. This speeds up product creation.

Use consistent naming

Standardize material names across your catalog (e.g., always “Recycled Polyester” not “Rec. Polyester”).

Complete certification data

Add full certification details including expiry dates. This builds consumer trust.

Aim for 100% composition

Strive for complete composition data. Partial data reduces transparency.

Use variant overrides sparingly

Only override at the variant level when materials actually differ. Over-use makes data harder to maintain.

Review country of origin data

Country of origin appears in digital passports. Ensure it’s accurate and up to date.

Common workflows

Adding a new material to multiple products

Create the material in Settings → Materials
Open each product that uses this material
Add the material and percentage in the Materials section
Save the product

The material data (country, certification) is automatically included.

Updating a certification

Go to Settings → Certifications
Edit the certification (e.g., update expiry date)
Save changes

All materials linked to this certification automatically reflect the update across all products.

Handling multi-component products

For products with multiple components (e.g., a jacket with shell and lining):Option 1: Weighted average composition Calculate overall percentages and list materials once:

50% Recycled Polyester (shell)
30% Organic Cotton (lining)
20% Recycled Down (insulation)

Option 2: Variant-level composition Create variants for major components and use variant overrides:

Variant: “Shell” → 100% Recycled Polyester
Variant: “Lining” → 100% Organic Cotton

Platform Setup

Data Management

Advanced

Materials and composition

Material catalog

Creating materials

Material certifications

Product composition

Product-level composition

Variant-level composition

Adding materials in the product form

Material selection

Percentage entry

Country display

Data validation

Material data structure

Brand materials table

Product materials table

Variant materials table

Best practices

Common workflows

Build docs developers (and LLMs) love

Platform Setup

Data Management

Advanced

Documentation Index

​Material catalog

​Creating materials

​Material certifications

​Product composition

​Product-level composition

​Variant-level composition

​Adding materials in the product form

​Material selection

​Percentage entry

​Country display

​Data validation

​Material data structure

​Brand materials table

​Product materials table

​Variant materials table

​Best practices

​Common workflows

Build docs developers (and LLMs) love

Material catalog

Creating materials

Material certifications

Product composition

Product-level composition

Variant-level composition

Adding materials in the product form

Material selection

Percentage entry

Country display

Data validation

Material data structure

Brand materials table

Product materials table

Variant materials table

Best practices

Common workflows