Using Custom Fields

When building complex quotes in DealHub, you often need to include specific information from your CRM that goes beyond standard fields. Whether it's special pricing tiers, customer-specific discounts, or industry-specific requirements, custom fields make it possible to carry this crucial information into your quotes.

Why Use Custom Fields?

Custom fields serve as the bridge between your CRM and DealHub quotes. They enable you to:

• Create more accurate quotes by bringing in customer-specific information like negotiated rates or volume discounts.
• Build smarter pricing rules that consider factors unique to your business, such as customer loyalty status or market segment.
• Maintain data consistency by ensuring that important CRM data is reflected in your quotes and remains synchronized.
• Enable specialized workflows that match your business processes, such as approval chains based on custom criteria.

Think of custom fields as a way to extend DealHub's capabilities to match your exact business needs. Any important data point in your CRM can be made available in your quotes.

Available Custom Field Types

DealHub offers different types of custom fields, each designed for specific kinds of data. Choose the right type based on what information you need to capture:

numeric

Numeric Fields

Use numeric fields when you need to work with quantities, amounts, or any numerical values. Perfect for:

• Product quantities
• Custom pricing amounts
• Percentage discounts
• Volume thresholds

const revenueField = {
  name: 'annual_revenue',
  value: '1000000'  // Always stored as string
};

Empty values are automatically converted to 0, making calculations more reliable.

text

Text Fields

Text fields handle any kind of descriptive information. Ideal for:

• Product descriptions
• Customer notes
• Special instructions
• Reference numbers

const industryField = {
  name: 'industry_segment',
  value: 'Healthcare'
};

Can store up to 8,192 characters, perfect for detailed information.

text-list

Text List Fields

Use text lists when you need single or multiple selections from predefined options. Great for:

• Product categories
• Feature selections
• Service tiers
• Market segments

// Single selection
const categoryField = {
  name: 'product_category',
  value: ['Enterprise']  // Always an array
};

// Multiple selections
const featuresField = {
  name: 'selected_features',
  value: ['API Access', 'Advanced Security', 'Custom Branding']
};

Supports both single-select and multi-select options.

utc-date

UTC Date Fields

Date fields ensure consistent handling of temporal data across time zones. Essential for:

• Contract start dates
• Renewal deadlines
• Validity periods
• Implementation milestones

const contractDate = {
  name: 'contract_start_date',
  value: '2025-06-13'  // Always YYYY-MM-DD format
};

All dates are stored in UTC to prevent timezone issues.

Setting Up Custom Fields

To start using custom fields in your integration:

1. Work with your DealHub administrator to define the fields you need. They'll need to configure these in the CPQ system first.

2. Identify which type of field best suits each piece of data:

   • Numbers for quantities and amounts
   • Text for descriptions and notes
   • Lists for predefined options
   • Dates for temporal information

3. Map your CRM fields to the corresponding DealHub custom fields:

   const customFieldDefinitions = {
     annual_revenue: {
       type: 'numeric',
       description: 'Annual revenue in USD'
     },
     industry: {
       type: 'text',
       description: 'Customer industry sector'
     },
     product_features: {
       type: 'text_list',
       description: 'Selected product features',
       isMultiSelect: true
     },
     contract_date: {
       type: 'utc_date',
       description: 'Contract start date'
     }
   };

Field names are case-insensitive, making your integration more robust. However, it's good practice to maintain consistent naming.

Using Custom Fields in Quotes

Once configured, you can include custom fields when creating or updating quotes. The fields will:

• Automatically sync with your quote data
• Be available for use in pricing rules
• Appear in relevant quote sections
• Update when CRM data changes (for draft quotes)

Here's how to include custom fields when creating a quote:

const quoteData = {
  // Standard quote fields
  dealhub_user_id: "user_123",
  external_opportunity_id: "opp_456",
  
  // Custom fields
  custom_fields: [
    { name: 'annual_revenue', value: '1000000' },
    { name: 'industry', value: 'Healthcare' },
    { name: 'product_features', value: ['API Access', 'Custom Branding'] },
    { name: 'contract_start_date', value: '2025-06-13' }
  ]
};

Consider creating a field mapping utility to automatically transform your CRM data into the correct format for each field type.

Best Practices

• Keep field names descriptive and consistent
• Document your field mappings clearly
• Use the appropriate field type for each data point
• Validate data before sending to DealHub
• Keep field definitions up to date

Remember: custom fields are powerful tools for making your quotes more dynamic and accurate. Take time to plan your field structure to match your business needs.