Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Avelero/avelero/llms.txt

Use this file to discover all available pages before exploring further.

The Products API provides endpoints for managing products and their variants in your Digital Product Passport platform. Products represent the main items in your catalog, while variants represent different configurations (sizes, colors, etc.) of those products.

​
Key concepts

​
Products

Products are the core items in your catalog. Each product has:
  • Basic information: Name, description, category, season, manufacturer
  • Product handle: URL-friendly identifier used in DPP URLs (/[brandSlug]/[productHandle]/)
  • UPID: 16-character alphanumeric unique identifier auto-generated by the system
  • Status: Draft or published state
  • Attributes: Materials, environmental data, journey steps, weight, tags

​
Variants

Variants represent different configurations of a product (e.g., different sizes or colors). Each variant has:
  • Variant UPID: 16-character unique identifier
  • Attribute values: Defines the variant’s specific attributes (e.g., “Red”, “Large”)
  • SKU and barcode: For inventory and point-of-sale systems
  • Overrides: Variant-specific data that overrides product-level data

​
Product handles vs UPIDs

  • Product handle: Human-readable URL slug (e.g., organic-cotton-tee)
  • UPID: System-generated 16-character alphanumeric ID for QR code resolution
Both can be used to identify products in API calls. Handles are preferred for frontend operations, while UPIDs are used in QR codes.

​
Router structure

The Products API is organized under the products router: 
const result = await trpc.products.list.query({ ... });
const variant = await trpc.products.variants.create.mutate({ ... });

​
Available routers

  • products - Core CRUD operations for products
  • products.variants - Manage product variants
  • products.publish - Publish products and variants to create Digital Product Passports

​
Common patterns

​
Filtering and search

List endpoints support advanced filtering using FilterState structure: 
const products = await trpc.products.list.query({
  filters: {
    groups: [
      {
        id: "group-1",
        conditions: [
          {
            id: "cond-1",
            fieldId: "status",
            operator: "equals",
            value: "published"
          }
        ]
      }
    ]
  },
  search: "cotton",
  sort: {
    field: "createdAt",
    direction: "desc"
  }
});

​
Pagination

List endpoints use cursor-based pagination: 
const firstPage = await trpc.products.list.query({ limit: 50 });
const nextPage = await trpc.products.list.query({ 
  cursor: firstPage.meta.cursor,
  limit: 50 
});

​
Bulk operations

Many endpoints support bulk operations with selection modes: 
// Explicit selection (specific IDs)
await trpc.products.update.mutate({
  selection: {
    mode: "explicit",
    ids: ["uuid-1", "uuid-2"]
  },
  status: "published"
});

// Select all with filters
await trpc.products.delete.mutate({
  selection: {
    mode: "all",
    filters: { /* FilterState */ },
    excludeIds: ["uuid-to-keep"]
  }
});

​
Brand scoping

All product operations are scoped to the active brand. The API automatically validates that:
  • Products belong to the active brand
  • The brand_id parameter (when provided) matches the active brand context
This ensures data isolation between brands.

​
Error handling

The API uses standard tRPC error codes:
  • BAD_REQUEST - Invalid input, validation errors, duplicate values
  • NOT_FOUND - Product or variant not found for the active brand
  • INTERNAL_SERVER_ERROR - Unexpected errors
Error messages include specific details: 
try {
  await trpc.products.create.mutate({ ... });
} catch (error) {
  // error.message: "Product handle must contain only lowercase letters..."
  // error.code: "BAD_REQUEST"
}

​
Next steps

Create products

Learn how to create new products with attributes

Update products

Update single products or perform bulk updates

List products

Query and filter your product catalog

Build docs developers (and LLMs) love

Get started for freeTalk to us