## Custom Fields in m3ter

_Custom Fields_ in m3ter allow you to store custom data in the form of number or string values against m3ter entities in a way that does not directly affect the normal working operation of the m3ter platform. This capability can help you meet specific usage-based pricing and other operational business use cases. You can create Custom Fields for the following m3ter entities:

- **Organization**
- **Product**
- **Meter**
- **Plan**
- **Plan Template**
- **Account**
- **Account Plan**
- **Aggregation**
- **Compound Aggregation**
- **Contract**
- **Balance**
- **Balance Transaction Schedules**
- **Balance Charge Schedules**
- **Plan Group**

### Using Custom Fields

You can reference the values you store using Custom Fields in Derived Field and Compound Aggregation calculations. This will affect how the platform behaves and gives you a wider scope for resolving complex usage-based pricing use cases. Here are some key points to note:

- You can create Custom Fields at _two levels_ 
  - **Organizational-level**
  - **Individual entities**

For example, if you want to reference a Custom Field for Account, say `cfAccount1`, in your calculations:

- You _must first create_ an Account Custom Field called `cfAccount1` at the Organizational-level.
- If you _do not create_ a Custom Field for an individual Account, the value of the _Organization-level field_ will be used.
- If you _do create_ a Custom Field for an individual Account, then that value will be referenced in the calculation.

### Limits and Constraints

- **Maximum number.** The maximum number of Custom Fields at Organization-level is **25**.
- **Duplicate Naming.** More than one Custom Field with the same name is not allowed.

### Important Exceptions

- Custom Fields for **Aggregations** and **Compound Aggregations** at both Organizational and individual entity levels are _NOT supported_ for referencing in Derived Field or Compound Aggregation calculations.
- You cannot create Custom Fields for Balances, Balance Transaction Schedules, Balance Charge Schedules, and Plan Groups at the Organization-level.

## Creating Custom Fields

### At Organizational-Level

You can create Custom Fields at the Organization-level in the Console. For more information, see the section on [Adding and Editing Custom Fields](https://docs.m3ter.com/guides/organization-and-access-management/viewing-and-editing-organization/adding-and-editing-custom-fields).

### At Individual Entity-Level

When creating or editing an individual entity that accepts Custom Fields in the Console, you’ll be able to add them. See the [Create Product](https://docs.m3ter.com/api/product/create-product) API call as an example.

## Reviewing Custom Fields

You can review any Custom Fields created for the entity on the metadata panel in your m3ter Organization. The Custom Fields will be listed, and you can **Copy** the _String_ or _Number_ value of a Custom Field to your clipboard.

### Custom Fields in Derived Field Calculations

In Derived Field calculations, the Custom Fields you can reference are:
- **Organization**
- **Meter**
- **Account**

If using Meters belonging to a specific Product, you can also reference Custom Fields added to a **Product**.

| Entity | Using Global Meters | Using Product Meters |
| --- | --- | --- |
| Organization | YES | YES |
| Meter | YES | YES |
| Product | NO | YES |
| Account | YES | YES |
| Account Plan | NO | NO |
| Plan | NO | NO |
| Plan Template | NO | NO |

### Format

When referencing Custom Fields in your Derived Field calculations, you can use formats like:
- `organization.<fieldName>`
- `meter.<fieldName>`
- `account.<fieldName>`
- `product.<fieldName>`

### Precedence

In Derived Field calculations, the entity-level value is used if defined; otherwise, the Organization-level value is used.

## Referencing Custom Fields in Compound Aggregation Calculations

### Range of Entities

- **Organization**
- **Meter**
- **Product**
- **Account**
- **Account Plan**
- **Plan**
- **Plan Template**

### Format

For Compound Aggregation calculations, use:
- `organization.<fieldName>`
- `meter.<fieldName>`
- `product.<fieldName>`
- `account.<fieldName>`
- `accountPlan.<fieldName>`
- `plan.<fieldName>`
- `planTemplate.<fieldName>`

### Precedence

In Compound Aggregation calculations, the general rule applies: the entity-level value is used if defined, otherwise the Organization-level value is used.

### Important Exceptions

- If you reference a Meter Custom Field in a Compound Aggregation calculation, the default value at the Organization-level is _**always used**_.