List Only the Fields You Need in Response

The Zuora Quickstart API allows you to select only the fields you want to be returned in the response.

Syntax

By default, any GET calls return all fields on the queried object. If you only need a subset of fields in the response, you can use the <object>.fields[] query parameter to include only the specified fields in the response:

<object>.fields[] = <field_name>

This query parameter provides you extended flexibility to suit your use cases. The <object> in the query parameter can be the primary object you query or any supported associated objects. The field_name can be any top-level fields that exist on the primary object or associated objects, separated by commas (,) . For example, if you only want to retrieve the account name and created time for a created account, include this query string in your request:

account.fields[]=created_time,name

For the supported associated objects available for use in the <object>.fields[] parameter, see the "Query Parameters" section for each GET operation in the Quickstart API Reference.

Examples

If you use the List accounts operation, by default, you will receive all fields on the Account objects in the response. If you are only interested in receiving the created time, account number, and custom fields in the response, you can include the account.fields[] query parameter in your request with created_time,account_number,custom_fields set as the value.

The following code snippet is an example for this case:

curl --request GET \
     --url 'https://rest.na.zuora.com/v2/account?account.fields[]=created_time,account_number,custom_fields'  
     --header 'Authorization: Bearer eeb5a22d679345ddaa1220640d2f440f'

After you send this request, the following response will be returned. Note that the custom fields can vary depending on the configured custom fields in your tenant.

{
	"next_page": null,
	"data": [
		{
			"created_time": "2023-03-30T17:19:54-07:00",
			"custom_fields": {
				"GenerateStatement__c": "Test Statement",
				"legal_entity__c": null,
				"RetryStatus__c": null,
				"StatementTemplate__c": "Template 1"
			},
			"account_number": "RC-00021184"
		}
	]
}

If you want to retrieve a subset of fields from a secondary object such as Payment Method that is associated with the primary object, you should include an additional expand[] parameter.

For example, if you are using the same "List accounts" operation as before and you want to retrieve the id, type, and state fields of any payment methods associated with the account, you can specify the expand[]=payment_methods and payment_methods.fields[]=type,state query parameters in your request as follows:

curl --request GET \ 
     --url 'https://rest.na.zuora.com/v2/account?account.fields[]=created_time,account_number,custom_fields&expand[]=payment_methods&payment_methods.fields[]=type,state' \ 
     --header 'Authorization: Bearer eeb5a22d679345ddaa1220640d2f440f'

With this request, you can get the following response:

{
	"next_page": null,
	"data": [
		{
			"created_time": "2023-04-18T06:36:18-07:00",
			"custom_fields": {
				"GenerateStatement__c": "Test Statement",
				"legal_entity__c": null,
				"RetryStatus__c": null,
				"StatementTemplate__c": "Template 1"
			},
			"account_number": "RC-00021212",
            "payment_methods": {
				"next_page": null,
				"data": [
					{
						"id": "8ad0950c844283030184506f3a8a76ef",
						"type": "card",
						"state": "active"
					},
					{
						"id": "8ad08aef82b04d1f0182b4880ffe55fb",
						"type": "ach_debit",
						"state": "active"
					}
                ]
            }
		}
	]
}

Bear in mind the following key points for listing fields on the associated objects:

• You cannot request nested fields (for example, custom_fields.legal_entity ) through the <object>.fields[] parameter. All nested fields will be returned when the top-level field such as custom_fields is specified.
• If you intend to retrieve the associated objects (secondary objects) on an object (primary object), you must also use the expand[] query parameter to expand on the secondary objects.