Knowledge Center

Knowledge Center > Billing and Payments > Billing Settings > Manage Custom Fields in Zuora Billing

Manage Custom Fields in Zuora Billing

You can create, view, edit, and remove Zuora Billing custom fields from the Zuora UI or through the Zuora APIs. You can also use the Customer Account Export and Import functions to export and import, respectively, the values for an account's custom fields.

Indexed and Non-indexed Custom Fields

Indexing custom fields in many instances offers performance gains. For example, tenants who perform synchronous API queries against their custom fields can expect to see performance gains. The following index options are available:

  • Indexed. Up to 10 custom fields per object are allowed to be designated as "Indexed."
  • Non-indexed. Up to 40 additional custom fields, that are not indexed, are allowed per object.
  • System Indexed
    • Tenants with a NetSuite integration will see additional, integration-related system custom fields.
    • For all tenants, the system custom fields used to report on Subscription metrics are available. See Subscription Field Descriptions for descriptions of these fields.

The following is an example of indexed and non-indexed custom fields for an object:

Example UI for Indexed and Non-indexed Custom Fields

If you have less than 10 custom fields per object, these fields are automatically indexed. If you have more than 10 custom fields on an object, the first 10 custom fields created are automatically indexed. You can manage indexed and non-indexed fields from the Zuora UI.

Create Custom Fields

To create a custom field:

  1. Click your username at the top right and navigate to Billing > Manage Custom Fields. The Maintain Custom Fields page appears.
  2. Select the object to which you want to add a new custom field. A list of custom fields that exist for the object is displayed.
  3. From the Indexed section or Non-Indexed section, click add new field. The New Custom Field page appears.
  4. Select the field type. The following types are available:
    • Picklist: Allows users to select a value from a list you define.
    • Text: Allows users to enter any combination of letters and numbers.
    • Date: Allows users to enter a date value or to select a date from the date picker.

    When creating a custom field of type Picklist, note that every 100 picklist values will add 15-20 milliseconds to the subscribe() call.

  5. Define the custom field. The following table describes the fields that are common to all custom field types. Depending on the field type you selected, there may be additional fields for you to define.
    Field Description

    Field Label

    The field name that is displayed on the Zuora UI.

    API Name

    The field name that is used in the Zuora APIs.

    The API Name is case-sensitive. When you use this custom fields in API calls, you must specify the API name exactly as defined in the correct case.

    The suffix "__c" (two underscores and the letter "c") is automatically appended to the end of the API name when the field is created.

    Description

    Optional description of what the new custom field is for.

    Required

    Whether the field is required.

    For example, if you create a required custom field for the Account object, users will need to specify a value for the field each time they create a new customer account.

    UI Read Only

    Whether the field is read-only on the Zuora UI.

    If selected, the custom field will not be updatable via the UI, but will be updatable via the APIs.

  6. Click save to save the custom field. Your custom field will now appear on the applicable object.

Edit Custom Fields

To edit a custom field, select the field, then click Edit. You can edit all of the properties of the field except for the data type. You cannot change the data type of an existing field, and you cannot remove items from a picklist list after saving the custom field. After editing a custom field, you must update your WSDL to reflect the changes.

To remove a custom field, click Remove, located to the right of the Required column in the list of fields.

Editing a field that is already in use may affect your existing integrations.

Considerations when Editing Custom Fields

If you edit an existing custom field, you must make the corresponding change to your WSDL and your integration client.

Because of this, changing the custom field definition can break existing clients if you do not make the corresponding offline change in your integration client.

Keep track of your custom fields so that you can verify your custom fields after updating your WSDL.

The following example describes some of the considerations to keep in mind while editing and deploying custom fields.

In the first example, Company A created a custom text field for the Account object with the following attributes:

  • Field LabelCF_Name
  • API NameCF_Name__c
  • Length200

Company A can then edit their WSDL to include the custom field CF_Name__c as one of the API fields of the Account object, and write business logic in their integration client (their own web site or a similar client) to collect information from their end-user for CF_Name__c and issue an API call to Zuora.

If Company A then changes the API Name to CF_Nick_Name__c without informing their customers, the existing customer clients will continue to send the name CF_Name__c to Zuora, rather than the updated name. In this case, the old name will not be recognized and will cause an error.

Similarly, if Company A changes the field length from 200 to 10 without notifying their customers, a client that sends the value "Jennifer Smith" as CF_Name__c to Zuora in the create call will receive an "Invalid_value" error.

Custom Fields on Invoice Objects

You can only update the "Invoice Detail" custom field, in other words the Invoice Item custom field, through a Zuora API call against the InvoiceItem object. This is only field on the Invoice Item that supports the update() call.

See Zuora Object Custom Fields for more information.

Last modified
03:24, 22 Dec 2016

Tags

Classifications

(not set)