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 | |
| 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.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 |
Billing Documents
The following table summarizes the supported query fields for the Billing Document object.
| Field | Example usage |
|---|---|
| updated_time | updated_time.GT:2020-03-10T07:12:12-07:00 |
| id | id.EQ:8ad09b2186e449290186e5bb40c04c3a |
| document_date | document_date.GT:2022-01-01 |
| account_id | account_id.EQ:402892c74c9193cd014c96bbe7c101f9 |
| state | state.NE:paid |
| type | type.EQ:invoice |
| total | total.LT:100 |
| remaining_balance | remaining_balance.LT:100 |
| billing_document_number | billing_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.
| Field | Example usage |
|---|---|
| updated_time | updated_time.GT:2020-03-10T07:12:12-07:00 |
| type | type.EQ:credit_memo |
| subscription_id | subscription_id.EQ:402892c74c9193cd014c96bbe7c101f9 |
| subscription_plan_id | subscription_plan_id.EQ:8ad09b2186e449290186e5bb3d7d4c13 |
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 |
| [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 |
| subscription_id | subscription_id.EQ:8ad08e017ffdeba30180003bd3794a1 |
| subscription_number | subscription_number.EQ:S-00012 |
| 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 |