Object Queries

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:

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

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

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
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

  • It is not supported to filter on unindexed standard or custom fields.
  • It is not supported to filter on the null value or an empty string ('').