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.
Brand attributes are variant dimensions that define how products can vary. Attributes can optionally link to taxonomy attributes for semantic meaning and standardization.
List attributes Retrieve all attributes for your brand with usage metrics.
const result = await trpc . catalog . attributes . list . query ();
Response Returns an array of attributes with metrics:
Array of attribute objects Brand that owns this attribute
Attribute name (e.g., “Color”, “Size”, “Material”)
Optional link to taxonomy attribute for semantic meaning
Number of attribute values defined for this attribute
Number of product variants using this attribute
The metrics include:
values_count: How many options (values) are defined for this dimensionvariants_count: How many product variants use this attribute List attributes with values Retrieve attributes grouped with their values in a single query.
const result = await trpc . catalog . attributes . listGrouped . query ();
Response Array of attributes with nested values Number of values for this attribute
Number of variants using this attribute
Array of attribute values Value name (e.g., “Red”, “Blue”)
Optional taxonomy value link
Display order (null values sorted last)
Number of variants using this value
Create attribute Create a new brand attribute.
const result = await trpc . catalog . attributes . create . mutate ({ name: "Size" , taxonomy_attribute_id: "550e8400-e29b-41d4-a716-446655440000" // optional });
Request Attribute name (1-100 characters) Examples: “Color”, “Size”, “Material”, “Fit”
Optional UUID linking to a taxonomy attribute for standardization When linked, this attribute gains semantic meaning from the taxonomy system.
Response ID of the created attribute
Validation rules
name is trimmed and must be 1-100 characters after trimmingAttribute names must be unique per brand (case-sensitive)
taxonomy_attribute_id must be a valid UUID if provided
Error handling Duplicate Name
Invalid UUID
{ "code" : "BAD_REQUEST" , "message" : "An attribute with this name already exists" }
Update attribute Update an existing attribute.
const result = await trpc . catalog . attributes . update . mutate ({ id: "550e8400-e29b-41d4-a716-446655440000" , name: "Product Color" });
Request New attribute name (1-100 characters)
Update or clear taxonomy link Pass null to remove the taxonomy link.
Response ID of the updated attribute
Only provided fields are updated. Omitted fields remain unchanged.
Error handling { "code" : "NOT_FOUND" , "message" : "attribute with ID '...' not found" }
Delete attribute Delete an attribute if it’s not in use.
const result = await trpc . catalog . attributes . delete . mutate ({ id: "550e8400-e29b-41d4-a716-446655440000" });
Request Response ID of the deleted attribute
Business rules Attributes cannot be deleted if they are referenced by any product variants.
The API performs a reference check before deletion:
Counts variant references via product_variant_attributes table
If count > 0, deletion is rejected
Otherwise, attribute and all its values are deleted
Error handling { "code" : "BAD_REQUEST" , "message" : "This attribute can't be deleted because it is referenced on your variants" }
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 . attributes . create . mutate ({ name: "Size" , taxonomy_attribute_id: "..." }); // result.data.id is typed as string // Type inference for list results const list = await trpc . catalog . attributes . list . query (); // list.data is typed as BrandAttributeData[] for ( const attr of list . data ) { console . log ( attr . name ); // typed as string console . log ( attr . variants_count ); // typed as number }
Schema types // Request schemas type CreateBrandAttributeSchema = { name : string ; // 1-100 chars taxonomy_attribute_id ?: string | null ; // UUID }; type UpdateBrandAttributeSchema = { id : string ; // UUID, required name ?: string ; // 1-100 chars taxonomy_attribute_id ?: string | null ; // UUID }; type DeleteBrandAttributeSchema = { id : string ; // UUID }; // Response types type BrandAttributeData = { id : string ; brandId : string ; taxonomyAttributeId : string | null ; name : string ; createdAt : string ; // ISO 8601 updatedAt : string ; // ISO 8601 }; type BrandAttributeWithMetrics = BrandAttributeData & { values_count : number ; variants_count : number ; };
Common patterns Creating a complete variant dimension Create an attribute and its values in sequence:
// 1. Create the attribute const attrResult = await trpc . catalog . attributes . create . mutate ({ name: "Color" }); const attributeId = attrResult . data . id ; // 2. Create values for the attribute const values = [ "Red" , "Blue" , "Green" ]; for ( const name of values ) { await trpc . catalog . attributeValues . create . mutate ({ attribute_id: attributeId , name }); }
For bulk value creation, use the batch endpoint:
await trpc . catalog . attributeValues . batchCreate . mutate ({ values: [ { attribute_id: attributeId , name: "Red" }, { attribute_id: attributeId , name: "Blue" }, { attribute_id: attributeId , name: "Green" } ] });
Checking usage before deletion const attrs = await trpc . catalog . attributes . list . query (); // Find unused attributes const unused = attrs . data . filter ( attr => attr . variants_count === 0 ); // Safe to delete for ( const attr of unused ) { await trpc . catalog . attributes . delete . mutate ({ id: attr . id }); }