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.

Both the filter[] and sort[] parameters are case-insensitive matching.

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 case-insensitive matching with EQ, NE, and IN.

String type fields like email and name support case-insensitive 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
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 fitler custom objects using the SW or NE operator.