Expand, Filter, Fields, and Sort

When you query records from Zuora objects, the following query parameters enable you to flexibly customize the returned results:

• expand[]: With this query parameter specified, you can expect to reduce the number of requests you make to the Zuora API by expanding objects in responses.
• filter[]: The filter query string.
• <object>.fields[]: Allows you to specify which fields to be returned in the response.
• sort[]: A case-sensitive query parameter that specifies the sort order of the listed results in the response. e array-type properties are specified for the sort[] parameter, they are ignored.

Expand responses

This guide describes how to request additional properties from the API. You will learn to modify your requests to include:

• properties from related objects
• properties from distantly related objects
• additional properties on all objects in a list

We also provide the supported fields on each expandable object.

How it works

The Zuora API is organized into resources represented by objects with state, configuration, and contextual properties. These objects all have unique IDs that you can use to retrieve, update, and delete them. The API also uses these IDs to link related objects together. A Billing Document, for example, links to an Account by the Account ID.

{
  "id": "2c93808457d787030157e031d86c4c57",
  "account_id": "402892c74c9193cd014c91d35b0a0132",
  ...
}

In cases where you need information from a linked object, you can retrieve the linked object in a new call using its ID. However, this approach requires two API requests to access just one value. If you need information from multiple linked objects, each would also require separate requests, which adds to the latency and complexity of your application.

curl -X GET 
'https://rest.sandbox.na.zuora.com/v2/accounts?expand%5B%5D=subscriptions&expand%5B%5D=payment_methods' 
-H 'Authorization: Bearer aa69290d875f4cfb97b226135ce278ad'

Account account = zuoraClient.accounts().getAccount(
"2c92c0f86cbe335a016cbece4a434ada",
Arrays.asList("subscriptions", "payment_methods")
);

const accounts = await zuoraClient.accounts.getAccounts({
    filter: [
       'account_number.EQ:A00000077',
    ],
    expand: [
       'subscriptions',
       'payment_methods',
    ]
});

It will return the subscriptions and payment methods associated with the account:

{
"id": "2c92c0f96abc17de016abd62bd0c5854",
...
"account_number": "RC-00000017",
"payment_methods": {
  "data": [
  {
    "id": "2c92c0f9710b79bd01711219e3ed2d9a",
    "account_id": "2c92c0f96abc17de016abd62bd0c5854",
    "type": "ach_debit",
  ...
  }
  ]
},
"subscriptions":
{
  "data": [
  {
    "id": "8ad0935e80bc8f360180c6f5a6e83ace",
    "subscription_number": "OpportunityNum1",
    "state": "Active",
    "account_id": "2c92c0f96abc17de016abd62bd0c5854",
  }
  ],
...
}
}

Expand multiple levels

curl -X GET 
'https://rest.sandbox.na.zuora.com/v2/accounts?expand%5B%5D=subscriptions.subscription_plans&expand%5B%5D=payment_methods' 
-H 'Authorization: Bearer aa69290d875f4cfb97b226135ce278ad'

Account account = zuoraClient.accounts().getAccount(
"2c92c0f86cbe335a016cbece4a434ada", Arrays.asList("subscriptions.subscription_plans", "payment_methods")
);

const accounts = await zuoraClient.accounts.getAccounts({
  filter: [
    'account_number.EQ:A100032',
  ],
  expand: [
    'subscriptions.subscription_plans',
    'payment_methods',
  ]
});

Request non-default includable properties

curl -X GET "https://rest.sandbox.na.zuora.com/v2/billing_documents/2c93808457d78703011d86c4c57" 
-d "expand[]=items"
-H "Authorization: Bearer 6e3b8958cc2b4b4bbfca2e4ab8d75126"

BillingDocument Invoice = zuoraClient.billingDocuments().getBillingDocument("2c92c0f86cbe335a016cbece4a434ada", Arrays.asList("items");

const newInvoice = await zuoraClient.billingDocuments.getBillingDocument('2c92c0f86cbe335a016cbece4a434ada',{
  expand: ['items']
});

Expandable objects and fields

Filter lists

Filter query syntax

A filter query clause consists of the following components:

• a field
• an operator
• a value

The filter query syntax is as follows:

You can combine multiple filter query clauses by separating them as different array elements. Note that the clauses are combined with the AND logic.

See the following sections for more information:

• Supported operators and corresponding examples of using
• Supported query fields for each object

Note: You can use any indexed custom field in your query filters and the fields documented here for each object.

Supported operators

The following table lists all supported operators that you can use to construct a list filter query, and an example for each operator.

Field types and operators

Supported query fields

Accounts

The following table summarizes the supported query fields for the Account object.

Contacts

The following table summarizes the supported query fields for the Contact object.

Subscriptions

The following table summarizes the supported query fields for the Subscription object.

Subscription Plans

The following table summarizes the supported query fields for the Subscription Plan object.

Subscription Items

The following table summarizes the supported query fields for the Subscription Item object.

Orders

The following table summarizes the supported query fields for the Order object.

Billing Documents

The following table summarizes the supported query fields for the Billing Document object.

Billing Document Items

The following table summarizes the supported query fields for the Billing Document Item object.

Invoices

The following table summarizes the related objects that support nested filters in the Invoice resource:

Invoice Items

The following table summarizes the related objects that support nested filters in the Invoice Item resource:

Credit Memos

The following table summarizes the related objects that support nested filters in the Credit Memo resource:

Credit Memo Items

The following table summarizes the related objects that support nested filters in the Credit Memo Item resource:

Debit Memos

The following table summarizes the related objects that support nested filters in the Debit Memo resource:

Debit Memo Items

The following table summarizes the related objects that support nested filters in the Debit Memo Item resource:

Payment Methods

The following table summarizes the supported query fields for the Payment Method object.

Payments

The following table summarizes the supported query fields for the Payment object.

Payment Runs

The following table summarizes the supported query fields for the Payment object.

Refunds

The following table summarizes the supported query fields for the Refund object.

Products

The following table summarizes the supported query fields for the Product object.

Plans

The following table summarizes the supported query fields for the Plan object.

Prices

The following table summarizes the supported query fields for the Price object.

Usage Records

The following table summarizes the supported query fields for the Usage Record object.

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

Examples

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"
		}
	]
}

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:

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.

Sorting fields in response