Expand Responses

This guide describes how to request additional properties from the API. You will learn to modify your requests to include:

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

We also provide the supported fields on each expandable object.

How it works

The Zuora API is organized into resources represented by objects with state, configuration, and contextual properties. These objects all have unique IDs that you can use to retrieve, update, and delete them. The API also uses these IDs to link related objects together. A Billing Document, for example, links to an Account by the Account ID.

{
  "id": "2c93808457d787030157e031d86c4c57",
  "account_id": "402892c74c9193cd014c91d35b0a0132",
  ...
}

In cases where you need information from a linked object, you can retrieve the linked object in a new call using its ID. However, this approach requires two API requests to access just one value. If you need information from multiple linked objects, each would also require separate requests, which adds to the latency and complexity of your application.

The API has an expand[] query parameter that allows you to retrieve linked objects in a single call, adding the object with all its properties and values.

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

curl -X GET 
'https://rest.sandbox.na.zuora.com/v2/accounts?expand%5B%5D=subscriptions&expand%5B%5D=payment_methods' 
-H 'Authorization: Bearer aa69290d875f4cfb97b226135ce278ad'

Account account = zuoraClient.accounts().getAccount(
"2c92c0f86cbe335a016cbece4a434ada",
Arrays.asList("subscriptions", "payment_methods")
);

const accounts = await zuoraClient.accounts.getAccounts({
    filter: [
       'account_number.EQ:A00000077',
     ],
    expand: [
       'subscriptions',
       'payment_methods',
    ]
});

It will return the subscriptions and payment methods associated with the account:

{
"id": "2c92c0f96abc17de016abd62bd0c5854",
...
"account_number": "RC-00000017",
"payment_methods": {
  "data": [
  {
    "id": "2c92c0f9710b79bd01711219e3ed2d9a",
    "account_id": "2c92c0f96abc17de016abd62bd0c5854",
    "type": "ach_debit",
  ...
  }
  ]
},
"subscriptions":
{
  "data": [
  {
    "id": "8ad0935e80bc8f360180c6f5a6e83ace",
    "subscription_number": "OpportunityNum1",
    "state": "Active",
    "account_id": "2c92c0f96abc17de016abd62bd0c5854",
  }
  ],
...
}
}

Expand multiple levels

If the value you want is nested deeply across multiple linked resources, you can reach it by recursively expanding using dot notation. For instance, if you want to know the payment method and the subscription plans of the subscriptions associated with an account, you can expand the subscription plan of the subscription and the payment method by passing subscriptions.subscription_plans and payment_methods into the expand array.

curl -X GET 
'https://rest.sandbox.na.zuora.com/v2/accounts?expand%5B%5D=subscriptions.subscription_plans&expand%5B%5D=payment_methods' 
-H 'Authorization: Bearer aa69290d875f4cfb97b226135ce278ad'

Account account = zuoraClient.accounts().getAccount(
"2c92c0f86cbe335a016cbece4a434ada", Arrays.asList("subscriptions.subscription_plans", "payment_methods")
);

const accounts = await zuoraClient.accounts.getAccounts({
  filter: [
    'account_number.EQ:A100032',
  ],
  expand: [
    'subscriptions.subscription_plans',
    'payment_methods',
  ]
});

Request non-default includable properties

If you query on a billing document, its included items are returned without details by default. You will not get any meaningful data in the returned items object. The details of this property is returned in responses only if the expand[] parameter is specified. For example:

curl -X GET "https://rest.sandbox.na.zuora.com/v2/billing_documents/2c93808457d78703011d86c4c57" 
-d "expand[]=items"
-H "Authorization: Bearer 6e3b8958cc2b4b4bbfca2e4ab8d75126"

BillingDocument Invoice = zuoraClient.billingDocuments().getBillingDocument("2c92c0f86cbe335a016cbece4a434ada", Arrays.asList("items");

const newInvoice = await zuoraClient.billingDocuments.getBillingDocument('2c92c0f86cbe335a016cbece4a434ada',{
  expand: ['items']
});

Expandable objects and fields

Not all objects or objects can be expanded. See the following table for a list of objects and the supported expand[] values: