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

# Custom attributes

## 1. Concepts

### What custom attributes are

Custom attributes are additional fields defined once at the account level and applied consistently across every record of a given object type. They extend Zenskar's standard data model to capture business-specific metadata for reporting, operations, and integrations.

Unlike free-form notes, custom attributes are typed. Each has a defined data type, which keeps values consistent across records and reliable for downstream use.

### Supported objects

Custom attributes are managed from **Settings > Custom Attributes** for three objects: Customer, Contract, and Product.

<Note>
  On demo accounts using the Contracts V3 experience, only the Customer section is currently shown; the Contract and Product sections are not available there.
</Note>

### The property key name

Every custom attribute has two identifiers: a display name shown throughout the product, and a property key name used by the API. The property key name is auto-generated from the display name when the attribute is created, and can be edited before the attribute is first saved.

### What changes after creation, and what does not

After a custom attribute is saved, its data type cannot be changed. This is enforced by the backend, and an attempt to change it is rejected. The property key name is not editable in the interface after creation, though this is a restriction in the interface rather than a rule enforced by the backend. Changing it is strongly discouraged regardless, since API integrations and webhooks reference an attribute by this key. Display name, default value, the mandatory toggle, and business entity scope remain editable at any time.

### Deleting a custom attribute

The Custom Attributes screen does not offer a way to delete an attribute; only Edit is available. A delete capability exists at the API level, gated by a separate permission, and performs a soft delete. Since the interface itself has no delete action, retiring an attribute through the interface is typically done by renaming it to signal it is no longer in use and turning off its mandatory toggle. This is a naming convention only, not a feature the system enforces or recognizes.

### Business entity scoping

A custom attribute can be scoped to all business entities or to one specific entity. When a business entity is selected on a customer or contract's create or edit form, only the attributes configured for that entity are loaded. Business entity scoping is not available for products, since products are global in scope.

### Data types

Supported data types when creating an attribute through this screen: Text, Integer, Boolean, Float, Array, and Dropdown.

### The API field name differs by object

<Warning>
  A custom attribute's values are read and written differently depending on the object. On the customer object, they appear under `custom_data`. On the contract and product objects, they appear under `custom_attributes`. Do not confuse this with a separate, unrelated field also named `custom_attributes` that exists on some objects for tagging. That is a different feature from the custom attribute definitions described on this page.
</Warning>

***

## 2. How-to guides

### Add a custom attribute

1. Go to **Settings > Custom Attributes**.
2. Scroll to the object to extend: Customer, Contract, or Product.
3. Click **Add New Property**.
4. Fill in the property details: Business Entity, Property Name, Property Key Name, Data Type, Default Value, and Mandatory.
5. Click **Add**.

<Note>
  Double-check the property key name and data type before saving. Neither can be changed afterward.
</Note>

### Edit a custom attribute

1. Go to **Settings > Custom Attributes**.
2. Find the attribute, open its actions menu, and select **Edit**.
3. Update the display name, default value, mandatory toggle, or business entity scope. Property key name and data type cannot be changed.
4. Click **Update**.

### Retire a custom attribute

1. Go to **Settings > Custom Attributes**.
2. Edit the attribute, and rename it to indicate it is no longer in use, for example by prefixing the name with `[DEPRECATED]`.
3. Turn off the **Mandatory** toggle.
4. Click **Update**.

### Fill in custom attributes on a record

1. Open the create or edit form for a Customer, Contract, or Product.
2. Select a business entity at the top of the form. This determines which custom attributes load, except for Product, which is not scoped by business entity.
3. Scroll to the **Custom Attributes** section.
4. Fill in the fields. Mandatory fields must be completed before saving.
5. Click **Create** or **Update**.

### Troubleshooting

* **Property Key Name or Data Type cannot be changed while editing**: both are locked after an attribute is created. Create a new attribute if a different key name or data type is needed.
* **There is no way to delete an attribute from this screen**: deletion is not available in the interface. Retire the attribute instead by renaming it and turning off its mandatory toggle.
* **The Contract or Product sections are missing from Custom Attributes**: this can happen on a demo account using the Contracts V3 experience, where only the Customer section is currently shown.

***

## 3. Reference

### Location

**Settings > Custom Attributes**.

### Fields

| Field             | Editable after creation | Notes                                                                                  |
| ----------------- | ----------------------- | -------------------------------------------------------------------------------------- |
| Business Entity   | Yes                     | Scope of the attribute: all entities or one specific entity. Not available for Product |
| Property Name     | Yes                     | The label shown in the interface                                                       |
| Property Key Name | No, in the interface    | Used by the API; auto-generated from the property name, editable before the first save |
| Data Type         | No                      | Enforced by the backend; an attempt to change it after creation is rejected            |
| Default Value     | Yes                     | Pre-filled on new records when the field is left blank                                 |
| Mandatory         | Yes                     | When on, the field must be completed before a record can be saved                      |

### Supported data types

| Data type | Description                             | Example use                      |
| --------- | --------------------------------------- | -------------------------------- |
| Text      | Alphanumeric strings                    | `internal_notes`, `account_tier` |
| Integer   | Whole numbers                           | `employee_count`                 |
| Boolean   | True or false                           | `is_tax_exempt`                  |
| Float     | Numbers with decimals                   | `discount_percentage`            |
| Array     | A list of multiple values               | `assigned_tags`                  |
| Dropdown  | A pre-defined set of selectable options | `region` (APAC, EMEA, AMER)      |

### API field name by object

| Object   | API field name      |
| -------- | ------------------- |
| Customer | `custom_data`       |
| Contract | `custom_attributes` |
| Product  | `custom_attributes` |

<Note>
  A separate, unrelated field also named `custom_attributes` exists on some objects for tagging. It is not the same feature as the custom attribute definitions on this page.
</Note>

### API endpoints

| Method  | Endpoint                                                                                 |
| ------- | ---------------------------------------------------------------------------------------- |
| `POST`  | [Create definition](/docs/api-reference/custom-attributes/create-custom-attribute-definition) |
| `GET`   | [Get definition](/docs/api-reference/custom-attributes/get-custom-attribute-definition)       |
| `GET`   | [List definitions](/docs/api-reference/custom-attributes/list-custom-attribute-definitions)   |
| `PATCH` | [Update definition](/docs/api-reference/custom-attributes/update-custom-attribute-definition) |

<Note>
  A delete endpoint also exists at the API level, performing a soft delete. It is not exposed in the interface, which offers editing only.
</Note>

### What is not currently supported in the interface

| Capability                                                                   | Status                                                                      |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Deleting an attribute                                                        | Not available in the interface. A delete capability exists at the API level |
| Contract and Product custom attribute sections on Contracts V3 demo accounts | Not available; only the Customer section is shown                           |