Skip to main content

Custom Fields in SOAP Objects

Zuora

Custom Fields in SOAP Objects

  1. Last updated
  2. Save as PDF

Custom fields allow you to add and store additional information on many objects in Zuora when standard fields do not meet your needs. You can create custom fields in the Zuora web application.

Custom Fields and Zuora WSDL

When you download the latest version of the Zuora WSDL, your tenant-specific custom fields are included automatically. You do not need to manually re-add custom fields after downloading the WSDL.

Zuora recommends that you keep track of your custom fields in case you need to recreate them at some point.

Z-Billing Custom Fields

Zuora provides custom fields on the following Z-Billing objects:

  • Account
  • Amendment
  • Contact
  • Subscription
  • Product
  • Product Rate Plan
  • Product Rate Plan Charge
  • (Subscription) Rate Plan
  • (Subscription) Rate Plan Charge
  • Invoice
  • Invoice Item (Detail)
  • Invoice Adjustment (Invoice Adjustment is deprecated on Production in WSDL version 64.0. Zuora recommends that you use the Invoice Item Adjustment instead.)
  • Invoice Item Adjustment
  • Taxation Item
  • Usage

Z-Payments Custom Fields

Zuora provides custom fields on the following Z-Payment objects:

  • Payments
  • Refunds

Z-Finance Custom Fields

Zuora provides custom fields on the following Z-Finance objects:

Using Custom Fields with the SOAP API

After creating the custom fields with Z-Billing, they are immediately accessible via the API. All fields can be used in the create(), query(), update(), and delete() calls. Account and Subscription custom fields can also be used in the subscribe() and subscribeWithExistingAccount() calls.

When downloading the Zuora WSDL from Z-Billing all your custom fields are included. 

When adding the custom fields to the WSDL, they must conform to the following rules:

  • Custom field names must append __c (double underscore and lowercase c) to the end of all custom fields' names (not display names)
  • The custom field name cannot contain spaces
  • The custom field must be of type string for the Picklist and Text fields
  • The custom field must be of type date for the Date fields
  • You must add custom fields to the existing fields in alphabetical order

For example, if you create two custom fields for the account object (MyCustomAccountField and AnotherCustomAccountField), the field names in the WSDL will be:

  • AnotherCustomAccountField__c
  • MyCustomAccountField__c

Your WSDL for the Account object will look like the following:

<complexType name="Account">
  <complexContent>
    <extension base="ons:zObject">
      <sequence>
        <element minOccurs="0" name="AccountNumber" nillable="true" type="string" />
        <element minOccurs="0" name="AdditionalEmailAddresses" nillable="true" type="string" />
        <element minOccurs="0" name="AllowInvoiceEdit" nillable="true" type="boolean" />
        <element minOccurs="0" name="AnotherCustomAccountField__c" nillable="true" type="string" />        <element minOccurs="0" name="AutoPay" nillable="true" type="boolean" />
        <element minOccurs="0" name="Balance" nillable="true" type="double" />
        <element minOccurs="0" name="Batch" nillable="true" type="string" />
        <element minOccurs="0" name="BillCycleDay" type="int" />
        <element minOccurs="0" name="BillToId" nillable="true" type="zns:ID" />
        <element minOccurs="0" name="CreatedDate" nillable="true" type="dateTime" />
        <element minOccurs="0" name="CrmId" nillable="true" type="string" />
        <element minOccurs="0" name="Currency" nillable="true" type="string" />
        <element minOccurs="0" name="CustomerServiceRepName" nillable="true" type="string" />
        <element minOccurs="0" name="DefaultPaymentMethodId" nillable="true" type="zns:ID" />
        <element minOccurs="0" name="Gateway" nillable="true" type="string" />
        <element minOccurs="0" name="InvoiceDeliveryPrefsEmail" nillable="true" type="boolean" />
        <element minOccurs="0" name="InvoiceDeliveryPrefsPrint" nillable="true" type="boolean" />
        <element minOccurs="0" name="InvoiceTemplateId" nillable="true" type="zns:ID" />
        <element minOccurs="0" name="MyCustomAccountField__c" nillable="true" type="string" />        <element minOccurs="0" name="Name" nillable="true" type="string" />
        <element minOccurs="0" name="Notes" nillable="true" type="string" />
        <element minOccurs="0" name="PaymentTerm" nillable="true" type="string"
        <element minOccurs="0" name="PurchaseOrderNumber" nillable="true" type="string" />
        <element minOccurs="0" name="SalesRepName" nillable="true" type="string" />
        <element minOccurs="0" name="SoldToId" nillable="true" type="zns:ID" />
        <element minOccurs="0" name="Status" nillable="true" type="string" />
        <element minOccurs="0" name="UpdatedDate" nillable="true" type="dateTime" />
      </sequence>
    </extension>
  </complexContent>
</complexType>

The custom fields appear in lines 8 and 23. 

  • <element minOccurs="0" name="AnotherCustomAccountField__c" nillable="true" type="string" />
  • <element minOccurs="0" name="MyCustomAccountField__c" nillable="true" type="string" />

Considerations when Editing Custom Fields

You can use the Zuora user interface to modify custom field definitions. See Manage Custom Fields for more information.

If you modify a custom field definition, you must make the corresponding change to your WSDL and your integration client. 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 Label: CF_Name
  • API Name: CF_Name__c
  • Length: 200

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.