Certifications API

Certifications represent third-party validations and standards that apply to your materials and products. Track certification details, issuing institutes, validity periods, and attach certification documents.

List certifications

Retrieve all certifications for your brand with usage metrics.

const result = await trpc.catalog.certifications.list.query();

Response

Returns an array of certifications with material usage counts:

data

array

required

Array of certification objects

string

required

Unique identifier (UUID)

title

string

required

Certification title (e.g., “GOTS”, “OEKO-TEX Standard 100”, “Fair Trade”)

certification_code

string | null

Certification number or code (e.g., “GOTS-2024-001”)

institute_name

string | null

Name of the certifying institute (e.g., “Control Union”, “OEKO-TEX”)

institute_email

string | null

Contact email for the institute

institute_website

string | null

Institute website URL

institute_address_line_1

string | null

Institute address line 1 (max 500 characters)

institute_address_line_2

string | null

Institute address line 2 (max 500 characters)

institute_city

string | null

Institute city (max 100 characters)

institute_state

string | null

Institute state/province (max 100 characters)

institute_zip

string | null

Institute postal/ZIP code (max 100 characters)

institute_country_code

string | null

ISO 3166-1 alpha-2 country code (e.g., “US”, “GB”, “DE”)

issue_date

string | null

ISO 8601 datetime when certification was issued

expiry_date

string | null

ISO 8601 datetime when certification expires

certification_path

string | null

File path or URL to the certification document (max 500 characters)

materials_count

number

required

Number of materials linked to this certification

created_at

string

required

ISO 8601 timestamp

updated_at

string

required

ISO 8601 timestamp

The materials_count metric shows how many materials reference this certification.

Create certification

Create a new certification entry.

const result = await trpc.catalog.certifications.create.mutate({
  title: "GOTS (Global Organic Textile Standard)",
  certification_code: "GOTS-2024-001",
  institute_name: "Control Union",
  institute_email: "info@controlunion.com",
  institute_website: "https://www.controlunion.com",
  institute_country_code: "NL",
  issue_date: "2024-01-15T00:00:00Z",
  expiry_date: "2025-01-15T00:00:00Z",
  certification_path: "https://storage.example.com/certs/gots-2024.pdf"
});

Request

title

string

required

Certification title (1-100 characters)Examples: “GOTS”, “OEKO-TEX Standard 100”, “Fair Trade Certified”, “Bluesign”

certification_code

string

Certification number or reference code (1-100 characters)Examples: “GOTS-2024-001”, “CU-875432”, “FT-2024-12345”

institute_name

string

Name of the certifying organization (1-100 characters)Examples: “Control Union”, “OEKO-TEX Association”, “Fair Trade USA”

institute_email

string

Contact email for the instituteMust be a valid email address format.

institute_website

string

Institute website URLMust be a valid URL format (e.g., https://example.com).

institute_address_line_1

string

First line of institute address (1-500 characters)

institute_address_line_2

string

Second line of institute address (1-500 characters)

institute_city

string

Institute city (1-100 characters)

institute_state

string

Institute state or province (1-100 characters)

institute_zip

string

Postal or ZIP code (1-100 characters)

institute_country_code

string

ISO 3166-1 alpha-2 country code (2 uppercase letters)Examples: "US", "GB", "DE", "NL", "CH"

issue_date

string

ISO 8601 datetime when certification was issuedExample: "2024-01-15T00:00:00Z"

expiry_date

string

ISO 8601 datetime when certification expiresExample: "2025-01-15T00:00:00Z"

certification_path

string

File path or URL to the certification document (1-500 characters)Can be a file storage URL or internal path reference.

Response

data

object

required

string

required

ID of the created certification

Validation rules

title is required and must be 1-100 characters
All optional string fields have max lengths (see parameter descriptions)
institute_email must be a valid email format
institute_website must be a valid URL format
institute_country_code is automatically converted to uppercase and must be exactly 2 characters
issue_date and expiry_date must be valid ISO 8601 datetime strings

Error handling

{
  "code": "BAD_REQUEST",
  "message": "Invalid email format"
}

Update certification

Update an existing certification.

const result = await trpc.catalog.certifications.update.mutate({
  id: "550e8400-e29b-41d4-a716-446655440000",
  expiry_date: "2026-01-15T00:00:00Z",
  certification_path: "https://storage.example.com/certs/gots-2024-updated.pdf"
});

Request

string

required

Certification ID (UUID)

title

string

New certification title (1-100 characters)

certification_code

string | null

Update or clear certification code

institute_name

string | null

Update or clear institute name

institute_email

string | null

Update or clear institute email

institute_website

string | null

Update or clear institute website

institute_address_line_1

string | null

Update or clear address line 1

institute_address_line_2

string | null

Update or clear address line 2

institute_city

string | null

Update or clear city

institute_state

string | null

Update or clear state

institute_zip

string | null

Update or clear ZIP code

institute_country_code

string | null

Update or clear country code

issue_date

string | null

Update or clear issue date

expiry_date

string | null

Update or clear expiry date

certification_path

string | null

Update or clear certification document path

Response

data

object

required

string

required

ID of the updated certification

Only provided fields are updated. Omitted fields remain unchanged. To explicitly clear a nullable field, pass null.

Error handling

{
  "code": "NOT_FOUND",
  "message": "certification with ID '...' not found"
}

Delete certification

Delete a certification from your catalog.

const result = await trpc.catalog.certifications.delete.mutate({
  id: "550e8400-e29b-41d4-a716-446655440000"
});

Request

string

required

Certification ID (UUID)

Response

data

object

required

string

required

ID of the deleted certification

Deleting a certification does not check for material references. Materials referencing this certification will have their certification_id set to null via cascade.

Error handling

{
  "code": "NOT_FOUND",
  "message": "certification with ID '...' not found"
}

TypeScript types

All procedures are fully typed when using the tRPC client:

import type { AppRouter } from "@v1/api";
import { createTRPCClient } from "@trpc/client";

const trpc = createTRPCClient<AppRouter>({
  // ... config
});

// Fully typed request and response
const result = await trpc.catalog.certifications.create.mutate({
  title: "GOTS",
  certification_code: "GOTS-2024-001",
  issue_date: "2024-01-15T00:00:00Z",
  expiry_date: "2025-01-15T00:00:00Z"
});
// result.data.id is typed as string

// Type inference for list results
const list = await trpc.catalog.certifications.list.query();
// list.data is typed as Certification[]
for (const cert of list.data) {
  console.log(cert.title); // typed as string
  console.log(cert.expiry_date); // typed as string | null
  console.log(cert.materials_count); // typed as number
}

Schema types

// Request schemas
type CreateCertificationSchema = {
  title: string; // 1-100 chars, required
  certification_code?: string; // 1-100 chars
  institute_name?: string; // 1-100 chars
  institute_email?: string; // valid email
  institute_website?: string; // valid URL
  institute_address_line_1?: string; // 1-500 chars
  institute_address_line_2?: string; // 1-500 chars
  institute_city?: string; // 1-100 chars
  institute_state?: string; // 1-100 chars
  institute_zip?: string; // 1-100 chars
  institute_country_code?: string; // 2-char uppercase
  issue_date?: string; // ISO 8601 datetime
  expiry_date?: string; // ISO 8601 datetime
  certification_path?: string; // 1-500 chars
};

type UpdateCertificationSchema = {
  id: string; // UUID, required
  title?: string;
  certification_code?: string | null;
  institute_name?: string | null;
  institute_email?: string | null;
  institute_website?: string | null;
  institute_address_line_1?: string | null;
  institute_address_line_2?: string | null;
  institute_city?: string | null;
  institute_state?: string | null;
  institute_zip?: string | null;
  institute_country_code?: string | null;
  issue_date?: string | null;
  expiry_date?: string | null;
  certification_path?: string | null;
};

type DeleteCertificationSchema = {
  id: string; // UUID
};

// Response types
type Certification = {
  id: string;
  title: string;
  certification_code: string | null;
  institute_name: string | null;
  institute_email: string | null;
  institute_website: string | null;
  institute_address_line_1: string | null;
  institute_address_line_2: string | null;
  institute_city: string | null;
  institute_state: string | null;
  institute_zip: string | null;
  institute_country_code: string | null;
  issue_date: string | null; // ISO 8601
  expiry_date: string | null; // ISO 8601
  certification_path: string | null;
  created_at: string; // ISO 8601
  updated_at: string; // ISO 8601
};

type CertificationWithMetrics = Certification & {
  materials_count: number;
};

Common patterns

Creating a complete certification

const certification = await trpc.catalog.certifications.create.mutate({
  title: "GOTS (Global Organic Textile Standard)",
  certification_code: "GOTS-2024-001",
  institute_name: "Control Union",
  institute_email: "info@controlunion.com",
  institute_website: "https://www.controlunion.com",
  institute_address_line_1: "P.O. Box 22074",
  institute_city: "Amsterdam",
  institute_zip: "1100 CB",
  institute_country_code: "NL",
  issue_date: "2024-01-15T00:00:00Z",
  expiry_date: "2025-01-15T00:00:00Z",
  certification_path: "https://storage.example.com/certs/gots-2024.pdf"
});

Checking expiry dates

const certs = await trpc.catalog.certifications.list.query();

const now = new Date();
const expiringWithin90Days = certs.data.filter(cert => {
  if (!cert.expiry_date) return false;
  const expiry = new Date(cert.expiry_date);
  const daysUntilExpiry = (expiry.getTime() - now.getTime()) / (1000 * 60 * 60 * 24);
  return daysUntilExpiry > 0 && daysUntilExpiry <= 90;
});

console.log(`${expiringWithin90Days.length} certifications expiring soon`);

Finding unused certifications

const certs = await trpc.catalog.certifications.list.query();

// Find certifications not linked to any materials
const unused = certs.data.filter(cert => cert.materials_count === 0);

// Safe to delete if no longer needed
for (const cert of unused) {
  await trpc.catalog.certifications.delete.mutate({ id: cert.id });
}

Updating expiry dates

// Extend certification validity
await trpc.catalog.certifications.update.mutate({
  id: certificationId,
  expiry_date: "2027-01-15T00:00:00Z"
});

Linking to materials

// Create certification first
const cert = await trpc.catalog.certifications.create.mutate({
  title: "OEKO-TEX Standard 100",
  certification_code: "21.HUS.68339",
  issue_date: "2024-01-01T00:00:00Z",
  expiry_date: "2025-01-01T00:00:00Z"
});

// Link to material
await trpc.catalog.materials.create.mutate({
  name: "OEKO-TEX Certified Cotton",
  certification_id: cert.data.id,
  recyclable: true
});

Getting Started

Products

Catalog

Brand

DPP

Certifications API

List certifications

Response

Create certification

Request

Response

Validation rules

Error handling

Update certification

Request

Response

Error handling

Delete certification

Request

Response

Error handling

TypeScript types

Schema types

Common patterns

Creating a complete certification

Checking expiry dates

Finding unused certifications

Updating expiry dates

Linking to materials

Build docs developers (and LLMs) love

Getting Started

Products

Catalog

Brand

DPP

Documentation Index

​List certifications

​Response

​Create certification

​Request

​Response

​Validation rules

​Error handling

​Update certification

​Request

​Response

​Error handling

​Delete certification

​Request

​Response

​Error handling

​TypeScript types

​Schema types

​Common patterns

​Creating a complete certification

​Checking expiry dates

​Finding unused certifications

​Updating expiry dates

​Linking to materials

Build docs developers (and LLMs) love

List certifications

Response

Create certification

Request

Response

Validation rules

Error handling

Update certification

Request

Response

Error handling

Delete certification

Request

Response

Error handling

TypeScript types

Schema types

Common patterns

Creating a complete certification

Checking expiry dates

Finding unused certifications

Updating expiry dates

Linking to materials