> ## Documentation Index
> Fetch the complete documentation index at: https://flywheel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Properties

> Create and manage custom user properties to store additional data and enhance personalization

Custom properties allow you to store additional information about your users beyond the standard profile fields. They enable deeper personalization, better segmentation, and more targeted marketing campaigns by capturing business-specific data that matters to your organization.

## What are Custom Properties?

Custom properties are additional data fields you can attach to user profiles to store:

* **Business-specific Information**: Customer type, account tier, industry
* **Behavioral Data**: Preferences, settings, usage patterns
* **Calculated Values**: Lifetime value, engagement score, risk rating
* **External System Data**: CRM IDs, support ticket counts, subscription details
* **Demographic Information**: Company size, job title, location details

Unlike standard user properties (name, email, phone), custom properties are completely flexible and defined by your business needs.

## How Custom Properties are Created

Custom properties can be created in several ways:

### 1. Automatic Creation from Events

When Flywheel receives user data through events with `identify: true`, it automatically creates custom properties from properties within a `$set` object:

```javascript theme={null}
// When this event is received with identify: true
{
  user_id: 'user123',
  event: 'user_signup',
  identify: true,
  properties: {
    email: 'user@example.com',
    first_name: 'John',
    $set: {
      company_size: '50-100',      // → Creates "company_size" custom property
      industry: 'Technology',      // → Creates "industry" custom property
      utm_source: 'google_ads',    // → Creates "utm_source" custom property
      trial_type: 'premium'        // → Creates "trial_type" custom property
    }
  }
}

// Flywheel automatically creates custom properties for each field in $set
// Properties outside $set are not added as custom properties
```

<Note>
  Only properties within the `$set` object are extracted as custom properties. Standard user properties (email, first\_name, last\_name, phone, etc.) can still be passed at the root level of `properties` and will be set on the user record directly.
</Note>

### 2. Manual Creation in Settings

Create custom properties manually for better control and organization:

1. **Navigate to Settings**

   * Go to **Settings** → **Users** → **Custom Properties**
   * Click **Add Custom Property**

<Card title="Custom Properties Settings" horizontal icon="settings" href="https://app.flywheel.cx/dashboard/deeplink?target=/settings/users">
  Access custom properties configuration and management
</Card>

2. **Define the Property**

   * **Name**: Internal name used in API calls and data
   * **Display Name**: Human-readable name for the UI
   * **Description**: Explain what the property represents
   * **Type**: Choose the data type (string, number, boolean, date)

3. **Configure Options**
   * **Required**: Whether the property is mandatory
   * **Default Value**: Set a default if no value is provided
   * **Validation Rules**: Set constraints on acceptable values

## Property Types

Flywheel supports several property types to match your data:

### String Properties

Text-based information:

```javascript theme={null}
{
  industry: 'Technology',
  customer_tier: 'premium',
  preferred_language: 'en',
  utm_source: 'google_ads'
}
```

### Number Properties

Numeric values for calculations and comparisons:

```javascript theme={null}
{
  lifetime_value: 1250.00,
  login_count: 45,
  support_tickets: 3,
  engagement_score: 85
}
```

### Boolean Properties

True/false flags for binary characteristics:

```javascript theme={null}
{
  is_premium_user: true,
  email_verified: false,
  has_mobile_app: true,
  opted_in_marketing: false
}
```

### Date Properties

Timestamp-based information:

```javascript theme={null}
{
  trial_end_date: '2024-02-15T00:00:00Z',
  last_purchase_date: '2024-01-10T14:30:00Z',
  onboarding_completed_date: '2024-01-05T09:15:00Z'
}
```

## Managing Custom Properties

### Viewing Custom Properties

Access custom properties in several ways:

#### Settings Dashboard

* **Property List**: See all defined custom properties
* **Usage Statistics**: View which properties are most used
* **Data Types**: Review property types and configurations
* **Validation Rules**: Check constraints and requirements

#### User Profiles

* **Individual User View**: View and edit custom property values for specific users

<Card title="View User Profiles" horizontal icon="user" href="https://app.flywheel.cx/dashboard/deeplink?target=/users">
  Access individual user profiles and custom property values
</Card>

### Editing Custom Properties

Update custom property configurations:

1. **Navigate to Property Settings**

   * Go to **Settings** → **Users** → **Custom Properties**
   * Click on the property you want to edit

<Card title="Edit Custom Properties" horizontal icon="settings" href="https://app.flywheel.cx/dashboard/deeplink?target=/settings/users">
  Modify existing custom property configurations
</Card>

2. **Modify Configuration**

   * Update display name or description
   * Change validation rules
   * Modify default values
   * Adjust property type (with caution)

3. **Impact Assessment**
   * Review existing data before making changes
   * Consider impact on segments and workflows
   * Test changes in staging environment first