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}:{value}

For example, email.EQ:alawrence@zuora.com contains the following breakdown components:

Component Value
field email
operator EQ
value alawrence@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.

Operator Description Example
EQ Exact match operator currency.EQ:EUR
NE Returns objects that do not match the clause currency.NE:CAN
LT Less than operator quantity.LT:200
GT Greater than operator quantity.GT:200
SW Starts with operator account_name.SW:Acc
IN Specifies a list of values that will be returned name.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.

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:2c92c0f86a8dd422016a9e7a70116b0d
batch batch.EQ:batch1
bill_cycle_day bill_cycle_day.EQ:30
bill_to_id bill_to_id.EQ:2c92c08a6246fdf101626b1b3fe0144b
sold_to_id sold_to_id.NE:2c92c08a6246fdf101626b1b3fe0144b
communication_profile_id communication_profile_id.EQ:2c92c0f95be68649015bf14e001f2760
crm_id crm_id.SW:SF
currency currency.NE:GBP
default_payment_method_id default_payment_method_id.EQ:402892c74c9193cd014c96bbe7d901fd
invoice_template_id invoice_template_id.SW:INV
name name.SW:Amy
balance balance.LT:500
last_invoice_date last_invoice_date.GT:2020-03-10
parent_account_id parent_account_id.EQ:402892c74c9193cd014c96bbe7c101f9
account_number account_number.EQ:A100032
status status.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.

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:8ad08c0f7d0972ea017d0a705e8059ba
first_name first_name.SW:Amy
last_name last_name.SW:Mc
account_id account_id.EQ:402892c74c9193cd014c96bbe7c101f9
email email.EQ:alawrence@zuora.com
work_email work_email.EQ:amy.lawrence@gmail.com
work_phone work_phone.EQ:(888) 976-9056

Subscriptions

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

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:8ad09b2186cb32bd0186cce8a0455282
account_id account_id.EQ:402892c74c9193cd014c96bbe7c101f9
state state.NE:paused
subscription_number subscription_number.EQ:SUB10000
version version.EQ:1
contract_effective contract_effective.EQ:2022-01-01
invoice_owner_account_id invoice_owner_account_id.EQ:8ad0823f8455bb400184633077e63aaf
start_date start_date.GT:2022-07-01
end_date end_date:LT:2022-12-31
latest_version latest_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.

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:8ad09e8086255d9c0186263fe0346c4a
subscription_id subscription_id.EQ:8ad09c4b80da79ad0180dd1c0f5937cb
product_id product_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.

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:8ad0889d86da5d7f0186db4ad79f79dd
subscription_plan_id subscription_plan_id.EQ:8ad0889d86da5d7f0186db4ad79f79db
subscription_item_number subscription_item_number.EQ:C-00050021

Orders

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

Field Example usage
updated_time updated_time.GT:2023-03-10T07:12:12-07:00
id id.EQ:8ad093fb8a935d40018a94e199ad2456
order_date order_date.GT:2023-03-10
order_number order_number.EQ:O-00024364
account_id account_id.EQ:8ad0889d86da5d7f0186db4ad79f79dd
[subscription][state] [subscription][state].EQ:active

Invoices

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

Field Example usage
id id.EQ:8ad08d2986bfcd2b0186c3878c725089
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
account_id account_id.EQ:8ad08d29857fc0ec0185829faf0507d7
document_date document_date.GT:2023-03-10
billing_document_number billing_document_number.EQ:INV00009299
remaining_balance remaining_balance.GT:100
state state.EQ:draft
reversed reversed.EQ:true
total total.GT:1000
due_date due_date.GT:2023-10-01
[items][id] [items][id].EQ:2c92c0856a8c7907016a9dda25dd796b

Invoice Items

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

Field Example usage
id id.EQ:8ad09b2186a19cc50186a3cbd10116f0
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
subscription_id subscription_id.EQ:8ad08d2986bfcd2b0186c3878ad8504d
subscription_plan_id subscription_plan_id.EQ:8ad08d2986bfcd2b0186c3878afc5053
invoice_id invoice_id.EQ:8ad08d2986bfcd2b0186c3878c725089
[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:

Field Example usage
id id.EQ:8ad0889d86bb645e0186bf2ada4a5f07
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
account_id account_id.EQ:8ad08d29857fc0ec0185829faf0507d7
document_date document_date.GT:2023-03-10
billing_document_number billing_document_number.EQ:CM000099
remaining_balance remaining_balance.GT:100
state state.EQ:posted
total total.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:

Field Example usage
id id.EQ:8ad0889d86bb645e0186bf2ada4a5f07
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
subscription_id subscription_id
invoice_item_id invoice_item_id.EQ:8ad08d298659570101865b0f99183614
credit_memo_id credit_memo_id.EQ:8ad0889d86bb645e0186bf2ada4a5f07
[taxation_items][id] [taxation_items][id].EQ:8ad0823f84c8a4500184c8cd329919b7

Debit Memos

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

Field Example usage
id id.EQ:8ad08e0184e174c00184e3d205584fd4
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
account_id account_id.EQ:8ad08d29857fc0ec0185829faf0507d7
document_date document_date.GT:2023-03-10
billing_document_number billing_document_number.EQ:DM00000256
remaining_balance remaining_balance.GT:100
state state.EQ:draft
total total.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:

Field Example usage
id id.EQ:8ad0889d86bb645e0186bf2ada4a5f07
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
subscription_id subscription_id
invoice_item_id invoice_item_id.EQ:8ad08d298659570101865b0f99183614
debit_memo_id debit_memo_id.EQ:8ad09e2085bf590d0185c10942ec3130
[taxation_items][id] [taxation_items][id].EQ:8ad09e2085bf590d0185c10943173133

Payment Methods

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

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:8f64d4d703ae472b6e1aa6d92b79b210
account_id account_id.EQ:402892c74c9193cd014c96bbe7c101f9
state state.EQ:active
type type.EQ:cc_ref

Payments

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

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
created_time created_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:8ad09c4b82aa84900182ada00dca1e22
account_id account_id.EQ:402892c74c9193cd014c96bbe7c101f9
payment_date payment_date.GT:2022-01-01
gateway_order_id gateway_order_id.EQ:12345678
gateway_state gateway_state.EQ:settled
payment_method_id payment_method_id.EQ:402892c74c9193cd014c96bbe7d901fd
payment_number payment_number.NE:1a2b3c4d
state state.NE:processed
amount amount.GT:100
remaining_balance remaining_balance.LT:100

Payment Runs

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

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:8ad09c4b82aa84900182ada00dca1e22
state state.EQ:completed

Refunds

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

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:8ad09c4b82aa84900182ada00dca1e22
account_id account_id.EQ:402892c74c9193cd014c96bbe7c101f9
payment_method_id payment_method_id.EQ:402892c74c9193cd014c96bbe7d901fd
refund_number refund_number.NE:RE1234
refund_date refund_date.GT:2023-01-01
reason_code reason_code.NE:null
amount amount.GT:100
state state.EQ:processed

Products

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

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:8ad081c686747d0101867b2ef24b783a
name name.SW:ZUO
sku sku.EQ:SKU123
start_date start_date.GT:2022-01-01
end_date end_date.LT:2023-01-01
[plans][id] [plans][id].EQ:8ad088718561b84d018579f52e2a2093

Plans

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

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:8ad081c686747d0101867b2ef24b783a
plan_number plan_number.IN:[PL-002,PL-017]
name name.SW:MONTHLY
product_id product_id.NE:8ad08aef7ffdebb80180003bd3272789
start_date start_date.GT:2022-01-01
end_date end_date.LT:2023-01-01
[prices][id] [prices][id].EQ:8ad08aef843cb3d701843fc06bf364ba

Prices

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

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:8ad081c686747d0101867b2ef24b783a
plan_id plan_id.EQ:8ad08e017ffdeba30180003bd58533ea
charge_model charge_model.EQ:flat_fee
charge_type charge_type.EQ:one_time
recurring_on recurring_on.EQ:1

Usage Records

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

Field Example usage
updated_time updated_time.GT:2020-03-10T07:12:12-07:00
id id.EQ:8ad081c686747d0101867b2ef24b783a
account_number account_number.EQ:A-12345
account_id account_id.EQ:8ad08e017ffdeba30180003bd58533ea
end_time end_time.LT:2020-03-10T07:12:12-07:00
start_time start_time.GT:2022-04-10T07:12:12-07:00
unit_of_measure unit_of_measure.EQ:Each