Percent Custom Field

Percent custom fields allow you to store percentage values for records. They automatically handle the % symbol for input and display, while storing the raw numeric value internally. Perfect for completion rates, success rates, or any percentage-based metrics.

Basic Example

Create a simple percent field:

mutation CreatePercentField {
  createCustomField(input: {
    name: "Completion Rate"
    type: PERCENT
  }) {
    id
    name
    type
  }
}

Advanced Example

Create a percent field with description:

mutation CreatePercentField {
  createCustomField(input: {
    name: "Success Rate"
    type: PERCENT
    description: "Percentage of successful outcomes for this process"
  }) {
    id
    name
    type
    description
  }
}

Input Parameters

CreateCustomFieldInput

Note: Project context is automatically determined from your authentication headers. No projectId parameter is needed.

Note: PERCENT fields do not support min/max constraints or prefix formatting like NUMBER fields.

Setting Percent Values

Percent fields store numeric values with automatic % symbol handling:

With Percent Symbol

mutation SetPercentWithSymbol {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    number: 75.5
  }) {
    id
    customField {
      value  # Returns { number: 75.5 }
    }
  }
}

Direct Numeric Value

mutation SetPercentNumeric {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    number: 100
  }) {
    id
    customField {
      value  # Returns { number: 100.0 }
    }
  }
}

SetTodoCustomFieldInput Parameters

Value Storage and Display

Storage Format

• Internal storage: Raw numeric value (e.g., 75.5)
• Database: Stored as Decimal in number column
• GraphQL: Returned as Float type

Display Format

• User interface: Client applications must append % symbol (e.g., “75.5%”)
• Charts: Displays with % symbol when output type is PERCENTAGE
• API responses: Raw numeric value without % symbol (e.g., 75.5)

Creating Records with Percent Values

When creating a new record with percent values:

mutation CreateRecordWithPercent {
  createTodo(input: {
    title: "Marketing Campaign"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "success_rate_field_id"
      value: "85.5%"
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
        value  # Percent is accessed here as { number: 85.5 }
      }
    }
  }
}

Supported Input Formats

Note: The % symbol is automatically stripped from input and added back during display.

Querying Percent Values

When querying records with percent custom fields, access the value through the customField.value.number path:

query GetRecordWithPercent {
  todo(id: "todo_123") {
    id
    title
    customFields {
      id
      customField {
        name
        type
        value  # For PERCENT type, contains { number: 75.5 }
      }
    }
  }
}

The response will include the percentage as a raw number:

{
  "data": {
    "todo": {
      "customFields": [{
        "customField": {
          "name": "Completion Rate",
          "type": "PERCENT",
          "value": {
            "number": 75.5
          }
        }
      }]
    }
  }
}

Response Fields

TodoCustomField Response

Important: Percent values are accessed through the customField.value.number field. The % symbol is not included in stored values and must be added by client applications for display.

Filtering and Querying

Percent fields support the same filtering as NUMBER fields:

query FilterByPercentRange {
  todos(filter: {
    customFields: [{
      customFieldId: "completion_rate_field_id"
      operator: GTE
      number: 80
    }]
  }) {
    id
    title
    customFields {
      number
    }
  }
}

Supported Operators

Range Filtering

For range filtering, use multiple operators:

query FilterHighPerformers {
  todos(filter: {
    customFields: [{
      customFieldId: "success_rate_field_id"
      operator: GTE
      number: 90
    }]
  }) {
    id
    title
    customFields {
      customField {
        value  # Returns { number: 95.5 } for example
      }
    }
  }
}

Percentage Value Ranges

Common Ranges

Example Values

Chart Aggregation

Percent fields support aggregation in dashboard charts and reports. Available functions include:

• AVERAGE - Mean percentage value
• COUNT - Number of records with values
• MIN - Lowest percentage value
• MAX - Highest percentage value
• SUM - Total of all percentage values

These aggregations are available when creating charts and dashboards, not in direct GraphQL queries.

Required Permissions

Error Responses

Invalid Percentage Format

{
  "errors": [{
    "message": "Invalid percentage value",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Not a Number

{
  "errors": [{
    "message": "Value is not a valid number",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Best Practices

Value Entry

• Allow users to enter with or without % symbol
• Validate reasonable ranges for your use case
• Provide clear context about what 100% represents

Display

• Always show % symbol in user interfaces
• Use appropriate decimal precision
• Consider color coding for ranges (red/yellow/green)

Data Interpretation

• Document what 100% means in your context
• Handle values over 100% appropriately
• Consider whether negative values are valid

Common Use Cases

1. Project Management

   • Task completion rates
   • Project progress
   • Resource utilization
   • Sprint velocity

2. Performance Tracking

   • Success rates
   • Error rates
   • Efficiency metrics
   • Quality scores

3. Financial Metrics

   • Growth rates
   • Profit margins
   • Discount amounts
   • Change percentages

4. Analytics

   • Conversion rates
   • Click-through rates
   • Engagement metrics
   • Performance indicators

Integration Features

With Formulas

• Reference PERCENT fields in calculations
• Automatic % symbol formatting in formula outputs
• Combine with other numeric fields

With Automations

• Trigger actions based on percentage thresholds
• Send notifications for milestone percentages
• Update status based on completion rates

With Lookups

• Aggregate percentages from related records
• Calculate average success rates
• Find highest/lowest performing items

With Charts

• Create percentage-based visualizations
• Track progress over time
• Compare performance metrics

Differences from NUMBER Fields

What’s Different

• Input handling: Automatically strips % symbol
• Display: Automatically adds % symbol
• Constraints: No min/max validation
• Formatting: No prefix support

What’s the Same

• Storage: Same database column and type
• Filtering: Same query operators
• Aggregation: Same aggregation functions
• Permissions: Same permission model

Limitations

• No min/max value constraints
• No prefix formatting options
• No automatic validation of 0-100% range
• No conversion between percentage formats (e.g., 0.75 ↔ 75%)
• Values over 100% are allowed

Related Resources

• Custom Fields Overview - General custom field concepts
• Number Custom Field - For raw numeric values
• Automations API - Create percentage-based automations