Retrieve an account

GET

/object-query/accounts/:key

GET

/object-query/accounts/:key

from zuora import ZuoraClient
client = ZuoraClient(
    token="YOUR_TOKEN_HERE",
)
client.object_queries.query_account_by_key(
    key="key",
    fields_array=[
        "id,createddate"
    ],
)

{
  "id": "8ad08eb292f6328c019318dcd43821b0",
  "createdById": "2c92c0f972a852360172bbe22ac551b6",
  "createdDate": "2024-11-10T17:35:45-08:00",
  "updatedById": "2c92c0f972a852360172bbe22ac551b6",
  "updatedDate": "2025-03-21T03:24:15-07:00",
  "accountNumber": "A00000130",
  "allowInvoiceEdit": false,
  "autoPay": false,
  "balance": 7300,
  "batch": "Batch1",
  "bcdSettingOption": "ManualSet",
  "billCycleDay": 1,
  "billToId": "8ad08eb292f6328c019318dcd45521b1",
  "creditBalance": 0,
  "currency": "USD",
  "invoiceDeliveryPrefsEmail": false,
  "invoiceDeliveryPrefsPrint": false,
  "invoiceTemplateId": "2c92c0f86cccaa59016cd5e0f500111d",
  "lastInvoiceDate": "2025-03-21",
  "name": "Bella Lawrence",
  "partnerAccount": false,
  "paymentMethodCascadingConsent": false,
  "soldToId": "8ad08eb292f6328c019318dcd47421b3",
  "status": "Active",
  "taxExemptStatus": "No",
  "totalInvoiceBalance": 7300,
  "unappliedBalance": 0,
  "mrr": 2950,
  "totalDebitMemoBalance": 0,
  "unappliedCreditMemoAmount": 0,
  "paymentTerm": "Net 30"
}

Retrieve the details of a specific Account object.

Authentication

AuthorizationBearer

Use Bearer {{token}} in the Authorization header for authentication.

Path parameters

keystringRequired

Object ID or Number.

Headers

Content-EncodingstringOptional

Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

Zuora-Org-IdsstringOptional

Comma separated IDs. If you have Zuora Multi-Org enabled, you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header.

The IDs must be a sub-set of the user’s accessible orgs. If you specify an org that the user does not have access to, the operation fails. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user’s accessible orgs.

Query parameters

pageSizeintegerOptional1-99Defaults to 10

The maximum number of results to return in a single page. If the specified pageSize is less than 1 or greater than 99, Zuora will return a 400 error.

cursorstringOptional

A cursor for use in pagination. A cursor defines the starting place in a list. For instance, if you make a list request and receive 100 objects, ending with next_page=W3sib3JkZXJ=, your subsequent call can include cursor=W3sib3JkZXJ= in order to fetch the next page of the list.

sort[]list of stringsOptional

A case-insensitive query parameter that specifies the sort order of the list, which can be either ascending (e.g. accountnumber.ASC) or descending (e.g. accountnumber.DESC). You cannot sort on properties in arrays. If the array-type properties are specified for the sort[] parameter, they are ignored.

expand[]list of enumsOptional

Allows you to expand responses by including related object information in a single call.

filter[]list of stringsOptional

A case-insensitive filter on the list.

fields[]list of stringsOptional

A case-insensitive query parameter that allows you to specify which fields are returned in the response.

includeNullFieldsbooleanOptionalDefaults to false

Specifies whether to include fields with the null value in the response.

If set to true, all fields will be returned in the response, including those with the null value.
If set to false, only fields with non-null values will be returned.

Response headers

Content-EncodingstringOptional

This header is returned if you specify the Accept-Encoding: gzip request header and the response contains over 1000 bytes of data.

Note that only the following MIME types support gzipped responses:

application/json
application/xml
text/html
text/csv
text/plain

RateLimit-LimitstringOptional

The request limit quota for the time window closest to exhaustion. See rate limits for more information.

RateLimit-Remainingdouble

The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.

RateLimit-Resetdouble

The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.

Zuora-Request-IdstringOptional

The Zuora internal identifier of the API call. You cannot control the value of this header.

Zuora-Track-IdstringOptional

A custom identifier for tracing the API call. If you specified a tracing identifier in the request headers, Zuora returns the same tracing identifier. Otherwise, Zuora does not set this header.

Concurrency-Limit-TypestringOptional

The type of the concurrency limit, which can be Default, High-volume transactions, or Object Query.

For more information, see Concurrent request limits.

Concurrency-Limit-Limitinteger

The total number of the permitted concurrent requests.

For more information, see Concurrent request limits.

Concurrency-Limit-Remaininginteger

The remaining number of the permitted concurrent requests.

For more information, see Concurrent request limits.

Response

idstringOptional

The unique identifier of the account.

createdByIdstringOptional

The unique identifier of the user who created the account.

createdDatedatetimeOptional

The date and time when the account was created.

updatedByIdstringOptional

The unique identifier of the user who last updated the account.

updatedDatedatetimeOptional

The date and time when the account was last updated.

accountNumberstringOptional

The account number that identifies the account.

additionalEmailAddressesstringOptional

An additional email addresse to receive email notifications.

allowInvoiceEditbooleanOptionalDefaults to false

Indicates whether associated invoices can be edited.

autoPaybooleanOptional

Indicates whether future payments are automatically collected when they are due during a payment run.

balancedoubleOptional

The customer's total invoice balance minus credit balance.

batchstringOptional

The alias name given to a batch. A string of 50 characters or less.

bcdSettingOptionenumOptional

Bill cycle day setting option. Indicates whether the account’s bill cycle day is managed manually or automatically.

ManualSet: The bill cycle day is explicitly set to a specific day of the month (1–31).
AutoSet: The bill cycle day is automatically determined by Zuora. The bill cycle day is assigned when the first subscription is created for the account.

This field is system-derived and read-only. Its value is automatically determined based on the billCycleDay field.

Allowed values:

billCycleDaylongOptional

Billing cycle day (BCD), the day of the month when a bill run generates invoices for the account.

billToIdstringOptional

The unique identifier of the bill-to contact associated with the account.

communicationProfileIdstringOptional

The unique identifier of the communication profile that Zuora uses when sending notifications to the account's contacts.

creditBalancedoubleOptional

The current credit balance on the account.

crmIdstringOptional<=100 characters

External identifier of the account in a CRM system.

currencystringOptional

A currency defined in the web-based UI administrative settings.

customerServiceRepNamestringOptional<=50 characters

Name of the account's customer service representative, if applicable.

defaultPaymentMethodIdstringOptional

ID of the default payment method for the account.

eInvoiceProfileIdstringOptional

ID of the e-invoice profile for this account.

Note: This field is available only if you have the E-Invoicing feature in Early Adopter phase enabled.

invoiceDeliveryPrefsEmailbooleanOptional

Indicates whether the customer wants to receive invoices through email.

invoiceDeliveryPrefsPrintbooleanOptional

Whether the customer wants to receive printed invoices, such as through postal mail.

invoiceTemplateIdstringOptional

Invoice template ID, configured in Billing Settings in the Zuora UI.

lastInvoiceDatedateOptional

Date of the most recent invoice for the account; null if no invoice has ever been generated.

lastMetricsUpdatedatetimeOptional

The date and time when account metrics are last updated, if the account is a partner account.

Note:

This field is available only if you have the Reseller Account feature enabled.
If you ever set the partnerAccount field to true for an account, the value of lastMetricsUpdate field is the time when the account metrics are last updated.

namestringOptional

The name of the account.

notesstringOptional

A string of up to 65,535 characters.

organizationIdstringOptional

The unique identifier of the organization to which the account belongs.

parentIdstringOptional

Identifier of the parent customer account for this Account object. The length is 32 characters. Use this field if you have Customer Hierarchy enabled.

partnerAccountbooleanOptional

Whether the customer account is a partner, distributor, or reseller.

Note: This field is available only if you have the Reseller Account feature enabled.

paymentMethodCascadingConsentbooleanOptional

true indicates the consent from your customer to use the Cascading Payment Method feature was collected. false indicates the consent was not collected and the Cascading Payment Method feature is not enabled.

purchaseOrderNumberstringOptional

The purchase order number provided by your customer for services, products, or both purchased.

salesRepNamestringOptional

Name of the account's sales representative, if applicable.

sequenceSetIdstring or nullOptional

The ID of the billing document sequence set to assign to the customer account. The billing documents to generate for this account will adopt the prefix and starting document number configured in the sequence set. If a customer account has no assigned billing document sequence set, billing documents generated for this account adopt the prefix and starting document number from the default sequence set.

shipToIdstringOptional

The unique identifier of the ship-to contact associated with the account.

soldToIdstringOptional

The unique identifier of the sold-to contact associated with the account.

statusenumOptional

The account status.

Allowed values:

taxCompanyCodestringOptional<=50 characters

Unique code that identifies a company account in Avalara. Note: This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support.

taxExemptCertificateIDstringOptional<=32 characters

ID of the customer tax exemption certificate. Applicable if you use Zuora Tax or Connect tax engines.

taxExemptCertificateTypestringOptional<=32 characters

Type of tax exemption certificate that the customer holds. Applicable if you use Zuora Tax or Connect tax engines.

taxExemptDescriptionstringOptional<=500 characters

Description of the tax exemption certificate that the customer holds. Applicable if you use Zuora Tax or Connect tax engines.

taxExemptEffectiveDatedateOptional

Date when the customer tax exemption starts, in YYYY-MM-DD format. Applicable if you use Zuora Tax or Connect tax engines.

taxExemptEntityUseCodestringOptional<=64 characters

A unique entity use code to apply exemptions in Avalara AvaTax. See Exempt Transactions for more details.

taxExemptExpirationDatedateOptional

Date when the customer tax exemption expires, in YYYY-MM-DD format. Applicable if you use Zuora Tax or Connect tax engines.

taxExemptIssuingJurisdictionstringOptional<=32 characters

Jurisdiction in which the customer tax exemption certificate was issued.

taxExemptStatusenumOptionalDefaults to No

Status of the account tax exemption. Applicable if you use Zuora Tax or Connect tax engines. Required if you use Zuora Tax.

Allowed values:

totalInvoiceBalancedoubleOptional

Total balance of all posted invoices.

unappliedBalancedoubleOptional

Total unapplied balance in this currency.

vATIdstringOptional

EU Value Added Tax ID.

mrrdoubleOptional

Monthly recurring revenue for the account.

totalDebitMemoBalancedoubleOptional

Total balance of all posted debit memos.

unappliedCreditMemoAmountdoubleOptional

The total unapplied amount of all posted credit memos in this currency.

creditMemoTemplateIdstringOptional

ID of the credit memo template that is used to generate credit memos for the account.

debitMemoTemplateIdstringOptional

ID of the debit memo template that is used to generate debit memos for the account.

paymentGatewaystringOptional

The name of the payment gateway instance. If null or left unassigned, the account will use the default gateway.

paymentTermstringOptional

A payment-terms indicator defined in the web-based UI administrative settings, for example, Net 30.

billToobjectOptional

shipToobjectOptional

soldToobjectOptional

defaultPaymentMethodobjectOptional

subscriptionslist of objectsOptional

paymentslist of objectsOptional

refundslist of objectsOptional

creditMemoslist of objectsOptional

debitMemoslist of objectsOptional

invoiceslist of objectsOptional

usageslist of objectsOptional

paymentMethodslist of objectsOptional

Errors

4XX

Client Request Error

500

Internal Server Error