Expand, Filter, Fields, and Sort

Quickstart API
v1 API

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.

Copy
Copied
{
  "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.

The API has an expand[] query parameter that allows you to retrieve linked objects in a single call, adding the object with all its properties and values.For example, if you want to access details of the subscriptions and payment methods associated with a customer account, you would retrieve the account and pass the subscription and payment_method properties to the expand array, which tells Zuora to include the entire Subscriptions and Payment Method objects in the response:
cURLJavaNode
Copy
Copied
curl -X GET 
'https://rest.sandbox.na.zuora.com/v2/accounts?expand%5B%5D=subscriptions&expand%5B%5D=payment_methods' 
-H 'Authorization: Bearer aa69290d875f4cfb97b226135ce278ad'
Copy
Copied
Account account = zuoraClient.accounts().getAccount(
"2c92c0f86cbe335a016cbece4a434ada",
Arrays.asList("subscriptions", "payment_methods")
);
Copy
Copied
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:

Copy
Copied
{
"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

If the value you want is nested deeply across multiple linked resources, you can reach it by recursively expanding using dot notation. For instance, if you want to know the payment method and the subscription plans of the subscriptions associated with an account, you can expand the subscription plan of the subscription and the payment method by passing subscriptions.subscription_plans and payment_methods into the expand array.
cURLJavaNode
Copy
Copied
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'
Copy
Copied
Account account = zuoraClient.accounts().getAccount(
"2c92c0f86cbe335a016cbece4a434ada", Arrays.asList("subscriptions.subscription_plans", "payment_methods")
);
Copy
Copied
const accounts = await zuoraClient.accounts.getAccounts({
  filter: [
    'account_number.EQ:A100032',
  ],
  expand: [
    'subscriptions.subscription_plans',
    'payment_methods',
  ]
});

Request non-default includable properties

If you query on a billing document, its included items are returned without details by default. You will not get any meaningful data in the returned items object. The details of this property is returned in responses only if the expand[] parameter is specified. For example:
cURLJavaNode
Copy
Copied
curl -X GET "https://rest.sandbox.na.zuora.com/v2/billing_documents/2c93808457d78703011d86c4c57" 
-d "expand[]=items"
-H "Authorization: Bearer 6e3b8958cc2b4b4bbfca2e4ab8d75126"
Copy
Copied
BillingDocument Invoice = zuoraClient.billingDocuments().getBillingDocument("2c92c0f86cbe335a016cbece4a434ada", Arrays.asList("items");
Copy
Copied
const newInvoice = await zuoraClient.billingDocuments.getBillingDocument('2c92c0f86cbe335a016cbece4a434ada',{
  expand: ['items']
});

Expandable objects and fields

Not all objects or objects can be expanded. See the following table for a list of objects and the supported expand[] values:
ResourceSupported expand[] value
Productplans, plans.prices
Planproduct, prices
Priceplan
Accountspayment_methods, payments, default_payment_method, billing_documents, bill_to, sold_to, subscriptions, subscriptions.subscription_plans, subscriptions.subscription_plans.plan, subscriptions.subscription_plans.subscription_items, usage_records, invoices, credit_memos, debit_memos
Subscriptionsubscription_plans, subscription_plans.subscription_items, account, account.bill_to, account.sold_to, account.payment_methods, invoice_owner_account, bill_to, invoice_items, prepaid_balances
Subscription Plansubscription, plan, subscription_items
Subscription Itemprice, subscription_plan
Invoiceaccount, items, bill_to
Invoice Itemsubscription, subscription_item, taxation_items, invoice, line_item
Credit Memoaccount, items, bill_to, applied_to
Credit Memo Itemsubscription, subscription_item, taxation_items, billing_document
Debit Memoaccount, items, bill_to
Debit Memo Itemsubscription, subscription_item, taxation_items, billing_document
Refundaccount, account.bill_to, account.sold_to, payment_method, applied_to, applied_to.payment, applied_to.items
Payment Methodaccount
Paymentaccount, account.bill_to, account.sold_to, payment_method, payment_applied_to
Orderaccount, line_items,line_items.invoice_items, subscriptions, subscriptions.subscription_plans, subscriptions.subscription_plans.subscription_items, order_actions
Usage Recordaccount
Custom Objectaccount

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:

field.operator:valueFor example, email.EQ:alawrence@zuora.com contains the following breakdown components:
ComponentValue
fieldemail
operatorEQ
valuealawrence@zuora.com

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.

OperatorDescriptionExample
EQExact match operatorcurrency.EQ:EUR
NEReturns objects that do not match the clausecurrency.NE:CAN
LTLess than operatorquantity.LT:200
GTGreater than operatorquantity.GT:200
SWStarts with operatoraccount_name.SW:Acc
INSpecifies a list of values that will be returnedname.IN:[Amy,Bella]

Field types and operators

All search fields support exact and case-sensitive matching with EQ, NE, and IN.String type fields like email and name support case-sensitive matching with SW.Numeric fields like amount and Date type fields like updated_time support numeric comparators like LT and GT.

Supported query fields

This section describes all supported filterable fields on each object and corresponding examples. Note that the [a][b] field indicates that you can filter results based on the a>b nested field.

Accounts

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:2c92c0f86a8dd422016a9e7a70116b0d
batchbatch.EQ:batch1
bill_cycle_daybill_cycle_day.EQ:30
bill_to_idbill_to_id.EQ:2c92c08a6246fdf101626b1b3fe0144b
sold_to_idsold_to_id.NE:2c92c08a6246fdf101626b1b3fe0144b
communication_profile_idcommunication_profile_id.EQ:2c92c0f95be68649015bf14e001f2760
crm_idcrm_id.SW:SF
currencycurrency.NE:GBP
default_payment_method_iddefault_payment_method_id.EQ:402892c74c9193cd014c96bbe7d901fd
invoice_template_idinvoice_template_id.SW:INV
namename.SW:Amy
balancebalance.LT:500
last_invoice_datelast_invoice_date.GT:2020-03-10
parent_account_idparent_account_id.EQ:402892c74c9193cd014c96bbe7c101f9
account_numberaccount_number.EQ:A100032
statusstatus.EQ:
[billing_documents][id][billing_documents][id].EQ:8ad0889d865429be018655c61c592aaa
[payment_methods][type][payment_methods][type].EQ:card
[subscriptions][state][subscriptions][state].EQ:active

Contacts

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8ad08c0f7d0972ea017d0a705e8059ba
first_namefirst_name.SW:Amy
last_namelast_name.SW:Mc
account_idaccount_id.EQ:402892c74c9193cd014c96bbe7c101f9
emailemail.EQ:alawrence@zuora.com
work_emailwork_email.EQ:amy.lawrence@gmail.com
work_phonework_phone.EQ:(888) 976-9056

Subscriptions

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8ad09b2186cb32bd0186cce8a0455282
account_idaccount_id.EQ:402892c74c9193cd014c96bbe7c101f9
statestate.NE:paused
subscription_numbersubscription_number.EQ:SUB10000
versionversion.EQ:1
contract_effectivecontract_effective.EQ:2022-01-01
invoice_owner_account_idinvoice_owner_account_id.EQ:8ad0823f8455bb400184633077e63aaf
start_datestart_date.GT:2022-07-01
end_dateend_date:LT:2022-12-31
latest_versionlatest_version.EQ:true
[subscription_plans][id][subscription_plans][id].EQ:8ad0889d86834d1e0186932012214142

Subscription Plans

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8ad09e8086255d9c0186263fe0346c4a
subscription_idsubscription_id.EQ:8ad09c4b80da79ad0180dd1c0f5937cb
product_idproduct_id.EQ:8ad08c0f7c9801a8017c9f3966864ee2
[subscription_items][id][subscription_items][id].EQ:8ad0889d86834d1e0186932012224143

Subscription Items

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8ad0889d86da5d7f0186db4ad79f79dd
subscription_plan_idsubscription_plan_id.EQ:8ad0889d86da5d7f0186db4ad79f79db
subscription_item_numbersubscription_item_number.EQ:C-00050021

Orders

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

FieldExample usage
updated_timeupdated_time.GT:2023-03-10T07:12:12-07:00
idid.EQ:8ad093fb8a935d40018a94e199ad2456
order_dateorder_date.GT:2023-03-10
order_numberorder_number.EQ:O-00024364
account_idaccount_id.EQ:8ad0889d86da5d7f0186db4ad79f79dd
[subscription][state][subscription][state].EQ:active

Billing Documents

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8ad09b2186e449290186e5bb40c04c3a
document_datedocument_date.GT:2022-01-01
account_idaccount_id.EQ:402892c74c9193cd014c96bbe7c101f9
statestate.NE:paid
typetype.EQ:invoice
totaltotal.LT:100
remaining_balanceremaining_balance.LT:100
billing_document_numberbilling_document_number.NE:INV10001
[items][id][items][id].EQ:8ad08c84858672100185a2662c6c1b4b

Billing Document Items

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
typetype.EQ:credit_memo
subscription_idsubscription_id.EQ:402892c74c9193cd014c96bbe7c101f9
subscription_item_idsubscription_item_id.EQ:8ad08c84858672100185a2662c6c1b4b
price_idprice_id.EQ:8ad08d2986bfcd2b0186c3878afc5053

Invoices

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

FieldExample usage
idid.EQ:8ad08d2986bfcd2b0186c3878c725089
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
account_idaccount_id.EQ:8ad08d29857fc0ec0185829faf0507d7
document_datedocument_date.GT:2023-03-10
billing_document_numberbilling_document_number.EQ:INV00009299
remaining_balanceremaining_balance.GT:100
statestate.EQ:draft
reversedreversed.EQ:true
totaltotal.GT:1000
[items][id][items][id].EQ:2c92c0856a8c7907016a9dda25dd796b

Invoice Items

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

FieldExample usage
idid.EQ:8ad09b2186a19cc50186a3cbd10116f0
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
subscription_idsubscription_id.EQ:8ad08d2986bfcd2b0186c3878ad8504d
subscription_item_idsubscription_item_id.EQ:8ad08d2986bfcd2b0186c3878afc5053
invoice_idinvoice_id.EQ:8ad08d2986bfcd2b0186c3878c725089
price_idprice_id.EQ:8ad0823f84c8a4500184c8cd329c19b8
[taxation_items][id][taxation_items][id].EQ:2c92c0856d82b3ab016da7379aeb28ac

Credit Memos

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

FieldExample usage
idid.EQ:8ad0889d86bb645e0186bf2ada4a5f07
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
account_idaccount_id.EQ:8ad08d29857fc0ec0185829faf0507d7
document_datedocument_date.GT:2023-03-10
billing_document_numberbilling_document_number.EQ:CM000099
remaining_balanceremaining_balance.GT:100
statestate.EQ:posted
totaltotal.GT:1000
[items][id][items][id].EQ:8ad0823f84c8a4500184c8cd329c19b8

Credit Memo Items

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

FieldExample usage
idid.EQ:8ad0889d86bb645e0186bf2ada4a5f07
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
subscription_idsubscription_id
invoice_item_idinvoice_item_id.EQ:8ad08d298659570101865b0f99183614
credit_memo_idcredit_memo_id.EQ:8ad0889d86bb645e0186bf2ada4a5f07
[taxation_items][id][taxation_items][id].EQ:8ad0823f84c8a4500184c8cd329919b7
subscription_item_idsubscription_item_id.EQ:8ad08c84858672100185a2662c6c1b4b
price_idprice_id.EQ:8ad08d2986bfcd2b0186c3878afc5053

Debit Memos

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

FieldExample usage
idid.EQ:8ad08e0184e174c00184e3d205584fd4
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
account_idaccount_id.EQ:8ad08d29857fc0ec0185829faf0507d7
document_datedocument_date.GT:2023-03-10
billing_document_numberbilling_document_number.EQ:DM00000256
remaining_balanceremaining_balance.GT:100
statestate.EQ:draft
totaltotal.GT:1000
[items][id][items][id].EQ:2c92c0f86a8dd422016a9ec8d52d6476

Debit Memo Items

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

FieldExample usage
idid.EQ:8ad0889d86bb645e0186bf2ada4a5f07
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
subscription_idsubscription_id
invoice_item_idinvoice_item_id.EQ:8ad08d298659570101865b0f99183614
debit_memo_iddebit_memo_id.EQ:8ad09e2085bf590d0185c10942ec3130
[taxation_items][id][taxation_items][id].EQ:8ad09e2085bf590d0185c10943173133
subscription_item_idsubscription_item_id.EQ:8ad08c84858672100185a2662c6c1b4b
price_idprice_id.EQ:8ad08d2986bfcd2b0186c3878afc5053

Payment Methods

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8f64d4d703ae472b6e1aa6d92b79b210
account_idaccount_id.EQ:402892c74c9193cd014c96bbe7c101f9
statestate.EQ:active
typetype.EQ:cc_ref

Payments

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
created_timecreated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8ad09c4b82aa84900182ada00dca1e22
account_idaccount_id.EQ:402892c74c9193cd014c96bbe7c101f9
payment_datepayment_date.GT:2022-01-01
gateway_order_idgateway_order_id.EQ:12345678
gateway_stategateway_state.EQ:settled
payment_method_idpayment_method_id.EQ:402892c74c9193cd014c96bbe7d901fd
payment_numberpayment_number.NE:1a2b3c4d
statestate.NE:processed
amountamount.GT:100
remaining_balanceremaining_balance.LT:100

Payment Runs

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8ad09c4b82aa84900182ada00dca1e22
statestate.EQ:completed

Refunds

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8ad09c4b82aa84900182ada00dca1e22
account_idaccount_id.EQ:402892c74c9193cd014c96bbe7c101f9
payment_method_idpayment_method_id.EQ:402892c74c9193cd014c96bbe7d901fd
refund_numberrefund_number.NE:RE1234
refund_daterefund_date.GT:2023-01-01
reason_codereason_code.NE:null
amountamount.GT:100
statestate.EQ:processed

Products

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8ad081c686747d0101867b2ef24b783a
namename.SW:ZUO
skusku.EQ:SKU123
start_datestart_date.GT:2022-01-01
end_dateend_date.LT:2023-01-01
[plans][id][plans][id].EQ:8ad088718561b84d018579f52e2a2093

Plans

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8ad081c686747d0101867b2ef24b783a
plan_numberplan_number.IN:[PL-002,PL-017]
namename.SW:MONTHLY
product_idproduct_id.NE:8ad08aef7ffdebb80180003bd3272789
start_datestart_date.GT:2022-01-01
end_dateend_date.LT:2023-01-01
[prices][id][prices][id].EQ:8ad08aef843cb3d701843fc06bf364ba

Prices

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8ad081c686747d0101867b2ef24b783a
plan_idplan_id.EQ:8ad08e017ffdeba30180003bd58533ea
charge_modelcharge_model.EQ:flat_fee
charge_typecharge_type.EQ:one_time
recurring_onrecurring_on.EQ:1

Usage Records

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

FieldExample usage
updated_timeupdated_time.GT:2020-03-10T07:12:12-07:00
idid.EQ:8ad081c686747d0101867b2ef24b783a
account_numberaccount_number.EQ:A-12345
account_idaccount_id.EQ:8ad08e017ffdeba30180003bd58533ea
subscription_idsubscription_id.EQ:8ad08e017ffdeba30180003bd3794a1
subscription_numbersubscription_number.EQ:S-00012
end_timeend_time.LT:2020-03-10T07:12:12-07:00
start_timestart_time.GT:2022-04-10T07:12:12-07:00
unit_of_measureunit_of_measure.EQ:Each

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,nameFor 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:

Copy
Copied
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.

Copy
Copied
{
	"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:
Copy
Copied
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

The sort[] query parameter is case-sensitive and it specifies the sort order of the listed results in the response. The value should be in the field.ASC|DESC format, which can be either ascending (for example, account_number.ASC) or descending (for example, account_number.DESC). You cannot sort on properties in arrays. If the array-type properties are specified for the sort[] parameter, they are ignored.