Skip to main content

Custom field definitions


Custom field definitions

The Data Model feature is In Development.

Zuora Data Model centralizes the management of custom field definitions that you attach to the existing Zuora business objects to accommodate your tenant-specific requirements.

This article describes how to access custom field definitions of Zuora business objects through Data Model UI. Previously, the custom object definitions were accessed through Settings UI. See Manage Custom Fields for the details.

View custom field definitions

To view custom fields of a Zuora business object:

  1. Navigate through Platform > Data Model.
  2. Click the ZUORA OBJECTS tab.
  3. Input the object name in the search box.
  4. Click the object name in the list of the search result and all the custom fields of the object will be displayed on the Manage Custom Fields page.
  5. View the custom field details through either of the following ways:
    • Click the custom field name in the custom field list view and the custom field detail page will be displayed.
    • Click the + left to the custom field API name and the custom field details will be expanded.

Create a new custom field definition

To create a new custom field:

  1. Click + at the top right corner on the Manage Custom Fields page.
  2. Fill in the following fields on the New Custom Field page. Every field marked with an asterisk is required.NewCustomFieldsForZuoraObjects.png
    • Field Name: The custom field name displayed on UI. The field name is required.
    • API Name: The API name of the custom field. The API name must start with a character, end with __c, and contain only alphanumeric characters and underscores. The API name cannot be edited once the custom field is created. The API name is required.
    • Description: The description of the custom field.
    • Field Type: Select a field type for the new custom field. See the following possible values of the field type. The field type cannot be changed once the custom field is created.
      • Text: You must define the length of the text type field. You can define the default text for a text type custom field.
      • Picklist: You must add at least one option for a picklist type field. You must make sure every picklist value is unique when you fill in picklist values. The picklist value is case-insensitive. For example, "Business" and "BUSINESS" are treated as the same value and cannot both be added. You can set a default value for a picklist type custom field.
      • Date: You can set a default date for a date type custom field. 
    • Required: If you select Required, Zuora will require you to specify a value for this custom field when creating an object.
    • UI Read Only: If you select UI Read Only, you are not able to update the value of the custom field via Zuora UI. However, you can update the value of it through Zuora API.
    • Indexed: Indexed custom fields have better performance than non-indexed custom fields. For example, if you are querying custom fields using synchronous API requests, you can expect the best performance if all of the custom fields are indexed. You can create up to 10 indexed custom fields and up to 40 non-indexed custom fields for each object. The Indexed value cannot be changed once the custom object is created.
  3. Click Submit.

The new custom field will be displayed in the custom field list view.

Edit a custom field definition

You can edit a custom field through either of the following navigation paths:

  • Click ... > Edit on the custom field detail page
  • Click the icon on the left of the custom field name in the custom field list view page. Then click Edit in the popup action list.

Note that the following fields cannot be edited once created:

  • API Name
  • Field Type
  • Indexed

Click Submit when you finish editing.

Delete a custom field definition

To delete a custom field:

  1. Click the icon on the left of the custom field name in the custom field list view.
  2. Click Delete in the popup action list.
  3. Click Yes in the Confirm Field Deletion dialog.

Note that you can only delete the custom fields that contain no data in all the references.


  • If you modify or delete a custom field, you must update any integration that accesses the field. For example, if you decrease the length of a field, an Invalid_value error will occur if any integration tries to send data that exceeds the new field length. You must check the maximum length of data sent from every integration.
  • The Required option is not available when defining custom fields for the following objects:
    • Amendments
    • Subscription Rate Plans
  • For the Usage object, do not create a custom field with the same name as a standard Zuora field. This avoids ambiguity when importing usage files.

Sample Use Cases 

Here are a few examples of how custom fields can be used:

  • Deploy custom fields to track and report on marketing and promotional campaigns.
    Custom fields can be set on various levels such as the product, product rate plan, product rate plan charge, subscription rate plan charge. When a customer signs up for a promotional product, you can run reports based on the product and determine the monthly recurring revenue for your promotional products versus a standard (non-promotional) product and see which product is selling better.
  • Use custom fields to tie back key data to other systems that are integrated with Zuora (including CRM, provisioning, ERP, and financial systems). Zuora's Z-Suite integration uses custom fields to track data both in Zuora and in NetSuite.
  • Track reasons for refunds and adjustments, for example, track refunds that result from "chargebacks" and adjustments due to "write-offs."


The custom field definitions have the following limitations:

  • You cannot share your global entity's custom fields with sub-entities through Data Model UI.
  • You can only query custom field data through the Data Query. Custom field query is not supported by ZOQL, export ZOQL, AQuA, or other reportings.