You can extend the business objects in your Zuora tenant by defining custom fields. Custom fields that you define are visible in the Zuora user interface and are available through the Zuora API. See How do I use custom fields? for examples of how your organization can leverage custom fields.
This article explains how to view, create, and modify custom field definitions in Zuora Settings. After you have defined a custom field, you can view and edit the field's value through the Zuora user interface, exports and imports, and the Zuora API.
For example, if you define a custom Account field, the field is included on the New Customer Account page and is supported in customer account imports.
View Custom Fields
To view the custom fields that are defined for a business object:
- If the object is related to accounts, subscriptions, invoices, or products, click your username at the top right and navigate to Settings > Billing.
- If the object is related to payments or refunds, click your username at the top right and navigate to Settings > Payments.
- If the object is related to accounting or revenue, click your username at the top right and navigate to Settings > Finance.
Click Manage Custom Fields.
Zuora lists the objects that support custom fields. For each object, Zuora displays the number of custom fields that have been defined.
Select the object.
"Invoice Detail" refers to the Invoice Item object.
Zuora lists the custom fields that have been defined for the object. The custom fields are listed in the following groups:
- 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.
- Non-Indexed - Non-indexed custom fields are functionally identical to indexed fields, but have lower performance.
If your Zuora tenant has integrations with external systems, you may see integration-related custom fields in the System group.
If you have the Multi-entity feature enabled, Zuora displays the sharing status of each custom field. If a custom field is defined in the global entity and has been shared with your entity, the value in the Shared column is "Yes" followed by the name of the parent entity. You cannot modify or delete a custom field that has been shared from the global entity.
See the "Share Custom Fields With Sub-entities" section for information about sharing custom fields that are defined in your entity.
Create Custom Fields
To define a custom field for a business object:
View the existing custom fields for the object. See the "View Custom Fields" section for more information.
In the Indexed or Non-Indexed group, click add new field.
Select a field type, then enter the field definition.
Note that 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.
If you select Required, Zuora will require users to specify a value for the field when creating an object. If you select UI Read Only, users will be able to update the field's value via the Zuora API but not via the Zuora UI.
__c(two underscores and the letter "c") is automatically appended to the end of the API name when Zuora creates the custom field.
Zuora creates the custom field. The custom field will then appear in the Zuora UI. For example:
When Zuora creates a custom field, Zuora does not apply the default value to existing objects.
This means that if you define a custom field, then immediately perform a ZOQL query such as
select BetaTester__c from Account, the query will not return any values for
To apply the default value to an existing object, you must modify the object via the Zuora UI or the Zuora API.
Modify Custom Fields
To modify the definition of a custom field:
In the list of custom fields for an object, click the label or API name of the field.
Zuora displays the definition of the custom field. For example:
Modify the field definition.
You cannot change the field type. If the field type is Picklist, you cannot remove picklist values.
If you modify or delete a custom field, you must update any integrations that access the field. For instance:
- If you change the label of a field, the API name of the field will also change. Any integration that continues to use the old API name will receive an error. You must update integrations to use the new API name.
- If you decrease the length of a field, any integration that sends data that exceeds the new field length will receive an "Invalid_value" error. You must check the maximum length of data that integrations could send.
Share Custom Fields With Sub-entities
If you have the Multi-entity feature enabled, you can share your global entity's custom fields with all sub-entities. By default, custom fields that you define in your global entity are not shared with any other entities.
After you share a custom field with sub-entities, each sub-entity has access to a custom field with the same definition (label, type, etc) as the global custom field. Values of the custom field are not copied between entities.
To share a custom field with all sub-entities of your global entity:
Use the entity switcher to switch to your global entity.
View the custom fields for the object that has the custom field. See the "View Custom Fields" section for more information.
Locate the custom field to share, then click Share.
In the dialog box that appears, click Yes.
The sharing status of the custom field changes to "Yes" after Zuora has shared the custom field with all sub-entities of your global entity.
You cannot delete a custom field while it is shared with sub-entities.
- The Required option is not available when defining custom fields for the following objects:
- 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.