Expand, filter, fields, and sort

The Object Query API contains GET operations that allow you to query objects in your Zuora tenant in an efficient, consistent, and flexible manner. With the expand[] and filter[] query parameters, you have the flexibility to retrieve related object information in a single call and define the returned response that best suits your needs. The sort[] query parameter allows you to sort the results in ascending or descending order based on the specified field.

For detailed information about the filterable, expandable, and filterable fields on each object, refer to the Query Parameters section for each API operation.

Note: The Object Query API is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available.

Using expand[] query parameter

Using the expand[] query parameter allows you to retrieve the following information:

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

For example, if you want to access details of payment methods associated with a customer account A00000001, you would retrieve the account and pass the paymentmethods properties to the expand array, which tells Zuora to include the entire Payment Method objects in the response:

Copy

Copied

curl --request GET \
--url 'https://rest.apisandbox.zuora.com/object-query/accounts/A00000001?=&expand%5B%5D=paymentmethods' \
--header 'Authorization: Bearer ${token}'

The response will include the payment methods associated with the specified account where accountNumber is A00000001.

Using filter[] query parameter

The following table lists all supported operators that you can use to construct a 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]
GE	Greater than or equal with operator	quantity.GE:200
LE	Less than or equal with operator	quantity.LE:200

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, LE, GT and GE.

Note: To filter on a field with the null value, specify a filter condition using the <field>.EQ:null syntax.

Example for using expand[], filter[], and sort[] query parameters

The following cURL example demonstrates how to query products with the following requirements:

Expand the Product Rate Plan object
Returns only the products in the "Base Products" category
The results are sorted by the ascending order of the product name

Copy

Copied

curl --request GET \
--url 'https://rest.apisandbox.zuora.com/object-query/products?=&filter%5B%5D=category.EQ%3ABase%20Products&expand%5B%5D=productrateplans&sort%5B%5D=name.ASC' \
--header 'Authorization: Bearer ${token}'

Throttling

Rate limits for Object Query operations are the same as the REST API rate limits. See Rate Limits for more information.

Limitations

Fields with the null value are not returned in the response.
It is not supported to filter on unindexed standard or custom fields.
Filtering on base objects is supported, but you cannot filter on the associated expandable objects. For example, when calling the List subscriptions operation, you can only filter on the Subscription objects. Filtering on the Account object is not supported.
To filter on an empty string, specify a filter condition using the <field>.EQ:%02%03 syntax. <field>.EQ:'' is not supported.
If you want to expose a Relationship-type field on custom objects through Object Query, you must set the field name to be suffixed with Id__c (case-sensitive). For example, RatePlanId__c. Otherwise, it cannot be queried through the Object Query API.
It is not supported to filter custom objects using the SW or NE operator.
The following objects are currently not supported:
- Catalog Group
- Product Rate Plan Definition
- Contact Snapshot
- Fulfillment
- Ramp
- Delivery Adjustment
- Invoice Schedule
- E-Invoicing objects
- Payment Gateway