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.

Copy
Copied
{
  "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:

cURLJavaNode
Copy
Copied
curl -X GET 
'https://rest.sandbox.na.zuora.com/v2/accounts?expand%5B%5D=subscriptions&expand%5B%5D=payment_methods' 
-H 'Authorization: Bearer aa69290d875f4cfb97b226135ce278ad'
Copy
Copied
Account account = zuoraClient.accounts().getAccount(
"2c92c0f86cbe335a016cbece4a434ada",
Arrays.asList("subscriptions", "payment_methods")
);
Copy
Copied
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:

Copy
Copied
{
"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.

cURLJavaNode
Copy
Copied
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'
Copy
Copied
Account account = zuoraClient.accounts().getAccount(
"2c92c0f86cbe335a016cbece4a434ada", Arrays.asList("subscriptions.subscription_plans", "payment_methods")
);
Copy
Copied
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:

cURLJavaNode
Copy
Copied
curl -X GET "https://rest.sandbox.na.zuora.com/v2/billing_documents/2c93808457d78703011d86c4c57" 
-d "expand[]=items"
-H "Authorization: Bearer 6e3b8958cc2b4b4bbfca2e4ab8d75126"
Copy
Copied
BillingDocument Invoice = zuoraClient.billingDocuments().getBillingDocument("2c92c0f86cbe335a016cbece4a434ada", Arrays.asList("items");
Copy
Copied
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:

Resource Supported expand[] value
Account payment_methods
payments
default_payment_method
billing_documents
bill_to
sold_to
subscriptions
subscriptions.subscription_plans
subscriptions.subscription_plans.plan
subscriptions.subscription_plans.subscription_items
usage_records
invoices
credit_memos
debit_memos
Subscription subscription_plans
subscription_plans.subscription_items
account
account.bill_to
account.sold_to
account.payment_methods
invoice_owner_account
bill_to
invoice_items
prepaid_balances
Subscription Plan subscription
plan
subscription_items
Subscription Item price
subscription_plan
Invoice account
items
bill_to
Invoice Item subscription
subscription_item
taxation_items
invoice
line_item
Credit Memo account
items
bill_to
applied_to
Credit Memo Item subscription
subscription_item
taxation_items
billing_document
Debit Memo account
items
bill_to
Debit Memo Item subscription
subscription_item
taxation_items
billing_document
Refund account
account.bill_to
account.sold_to
payment_method
applied_to
applied_to.payment
applied_to.items
Payment Method account
Payment account
account.bill_to
account.sold_to
payment_method
payment_applied_to
Product plans
plans.prices
Plan product
prices
Price plan
Order account
line_items
line_items.invoice_items
subscriptions
subscriptions.subscription_plans
subscriptions.subscription_plans.subscription_items
order_actions
Usage Record account
Custom Object account