Skip to main content
QuoteBase Logo
QuoteBase
Back to HomeGet Started
Back to Help Center

Custom Fields Setup

Define organization-specific fields without code changes

12 min read
Intermediate
1

What Are Custom Fields?

Custom fields let you add organization-specific columns to your RFQ line items without modifying code. They're stored as JSONB in the database (rfq_lines.custom_fields column) and validated automatically on both client and server.

Common Use Cases

  • Material specifications (6061-T6, 304 SS, ASTM A36)
  • Surface finishes (Anodized, Powder Coated, Galvanized)
  • Tolerances (±0.05mm, ±0.1mm, H7/g6)
  • Certifications required (ISO 9001, AS9100, ITAR)
  • Industry-specific requirements (Hardness, Coating thickness)
  • Drawing/specification references

Technical Benefits

  • No code deployment required - define fields in settings
  • Dual validation: client-side (React Hook Form + Zod) + server-side (PostgreSQL function)
  • Suppliers see custom fields and can reference them in quotes
  • Excel import/export automatically includes custom fields
  • Full API support (/v1/custom-fields endpoint)
  • Max 64KB JSONB per RFQ line (PostgreSQL limit)
2

Navigate to Custom Fields

Custom fields are managed at the organization level. Only users with Owner or Admin role can create/modify field definitions.

Access Path

Dashboard → Settings → Custom Fields

Important

If you don't see "Custom Fields" in settings, your role is Buyer or Manager. Ask your organization owner to grant you Admin access.

Pro Tip

Plan your custom fields before creating them. You cannot rename field keys after creation (data integrity constraint).

3

Create Field Definitions

Each custom field needs a definition specifying its key, label, type, and validation rules. Field definitions are stored in the custom_field_definitions table.

Required Fields

  • Field Key: Unique identifier (snake_case, e.g., material_grade)
  • Field Label: Display name shown in UI (e.g., "Material Grade")
  • Field Type: One of 6 types (see below)
  • Is Required: Checkbox for mandatory fields

Available Field Types

  • text - Short text (max 255 chars), e.g., part notes
  • number - Numeric values (integer or decimal), e.g., hardness, thickness
  • select - Single choice dropdown (define options), e.g., material grade
  • multi_select - Multiple choices (checkboxes), e.g., certifications
  • date - Date picker (ISO 8601 format), e.g., required delivery date
  • boolean - Yes/No checkbox, e.g., "Requires heat treatment"

Validation Rules

  • Max Length (text only): Character limit (1-255)
  • Min/Max Value (number only): Numeric range
  • Options (select/multi_select): Comma-separated allowed values
  • Default Value (optional): Pre-filled value for new RFQs

Important

Field keys must be alphanumeric with underscores only (^[a-z0-9_]+$). Once created, they cannot be changed due to data integrity. Good: material_grade, Bad: material-grade or materialGrade

4

Use Custom Fields in RFQs

Once defined, custom fields appear automatically in RFQ forms, Excel imports, and supplier quote forms.

Manual RFQ Creation

  1. Create new RFQ → Add line item
  2. Fill standard fields (description, quantity, unit)
  3. Scroll to "Custom Fields" section
  4. Fill required custom fields (marked with *)
  5. Optional fields can be left empty
  6. Save line item

Excel Import

Add columns matching your field keys (case-insensitive). E.g., if field_key is "material_grade", Excel column can be "Material Grade" or "material_grade". Auto-mapped during import.

Supplier Quote Forms

Suppliers see your custom field values (read-only) when quoting. They cannot edit them but can reference them in their pricing or notes.

5

Validation System (Technical)

QuoteBase validates custom fields in two layers: client-side (instant UI feedback) and server-side (data integrity enforcement).

Client-Side Validation

Function: validateCustomFields() in lib/custom-fields/validate.ts. Uses Zod schemas generated from field definitions. Validates on form submit and real-time on field blur.

Server-Side Validation

PostgreSQL function: validate_custom_fields_json(jsonb, uuid). Called via trigger on rfq_lines INSERT/UPDATE. Rejects transactions if validation fails. Protects against API bypass.

Validation Rules Applied

  • Type checking: Numbers must be numeric, dates must be ISO 8601
  • Required fields: Cannot be null or empty string if is_required=true
  • Select options: Value must exist in options array
  • Max length: Text fields truncated at max_length
  • Range checks: Numbers must be within min/max if specified

Important

Max JSONB size: 64KB per rfq_line row. If you have 100+ custom fields with long text values, you may hit this limit. Consider storing large data (PDFs, images) as file attachments instead.

6

Best Practices

Follow these guidelines to get the most out of custom fields without creating maintenance headaches.

  • Start small: Define 3-5 critical fields first, add more as needed
  • Use select over text: Prevents typos and ensures data consistency
  • Naming convention: Use snake_case for all field keys (material_grade, not materialGrade)
  • Document fields: Add clear descriptions so team members know what to enter
  • Plan for growth: You can add new fields anytime, but cannot delete fields with existing data
  • Test with Excel: Import a sample file to ensure field mapping works
Back to Help Center
Custom Fields Setup - QuoteBase Help