Account
An account is a customer account that collects all of the critical information about the customer, such as contact information, payment terms, and payment methods. This SOAP API reference describes the Account object and its fields.
Account Object
The Account object represents an individual customer account. Each Account object includes everything Zuora needs to bill and collect, such as addresses, payment methods, and payment terms.
Zuora uses the Account object to track all subscriptions, usage, and transactions for each customer account. Each account is a source of a recurring invoice stream.
Every subscription must be associated with an account. At least one active account must exist before any subscriptions can be created.
Supported Calls
You can use this object with the following calls:
Limits
Number of Subscriptions
The default maximum number of subscriptions allowed on an account is 12,000. However, if you have overridden the value of this limit for your tenant, the value will remain according to your configuration.
Zuora can increase the limit of subscriptions per account upon request. To increase the limit, see Zuora’s Performance Booster and Performance Booster Elite offerings.
Note that the method that Zuora uses to calculate the number of existing subscriptions on an account is explained as below.
When you create a new subscription on an account, the start and end dates of the subscription determine a time frame. When calculating the number of existing subscriptions on the account, Zuora only counts in those existing subscriptions that have a time frame that overlaps with the new subscription to be created. The time frame of an existing subscription is also determined by the start and end dates of the existing subscription. For an evergreen subscription, this time frame is without an end date.
Contacts per Account
100 contacts are allowed for each customer account.
Creating a Contract When Threshold is Exceeded
If you reach or exceed this limit, the following message is displayed:
You cannot create more than 100 contacts for each customer account. If you need to create this contact, please delete some others first.
Walkthroughs and use cases
You can see examples here:
Field Descriptions
All field names are case sensitive. Check enumerated values in descriptions to confirm capitalization and spacing. See Field Types for additional information.
| Name | Required to Create? | Allowed Operations | Description |
|---|---|---|---|
| optional | Create Query Update Delete Filter |
Unique account number assigned to the account. You can modify the account number of a customer account only if the account has no subscriptions or draft subscriptions only. Otherwise, the account number cannot be modified.
Type: string
|
|
| AdditionalEmailAddresses | optional | Create Query Update Delete Filter |
List of additional email addresses to receive email notifications.
Type: string |
| AllowInvoiceEdit | optional | Create Query Update Delete Filter |
Indicates if associated invoices can be edited. Type: boolean |
| AutoPay | optional | Create Query Update Delete Filter |
Indicates if future payments are automatically collected when they're due during a Payment Run. Type: boolean |
| Balance | NA |
Query |
Current outstanding balance for the account.
Type: decimal |
| Batch | conditional | Create Query Update Delete Filter |
Organizes your customer accounts into groups to optimize your billing and payment operations. Required if use the subscribe() call, optional for other supported calls. |
| BcdSettingOption | optional | Create Query Update Delete Filter |
Billing cycle day setting option.
Type: string |
| BillCycleDay | required | Create Query Update Delete Filter |
Billing cycle day (BCD) on which bill runs generate invoices for the account.
Type: int |
| BillToId |
optional |
Create Query Update Delete Filter |
ID of the person to bill for the account.
Type: zns:ID |
| CommunicationProfileId | optional | Create Query Update Delete Filter |
Associates the account with a specified communication profile.
Type: zns:ID |
| CreatedById | NA |
Query |
ID of the Zuora user who created the Account object.
Type: zns:ID |
| CreatedDate | NA |
Query |
Date when the Account object was created.
Type: dateTime |
| CreditBalance | NA |
Query |
Total credit balance for the account.
Type: decimal |
| CrmId | optional | Create Query Update Delete Filter |
CRM account ID for the account. Used in Salesforce integration.
Type: string |
| Currency | required | Create Query Update* Delete Filter |
Currency that the customer is billed in. See Currency for more information. You can update this value only when the account is in Type: string |
| CustomerServiceRepName | optional | Create Query Update Delete Filter |
Name of the account's customer service representative, if applicable.
Type: string |
| DefaultPaymentMethodId | optional | Create Query Update Delete Filter |
ID of the default payment method for the account. This field is required if the AutoPay field is set to true.
Type: zns:ID |
| Gateway | NA | NA | Deprecated at WSDL 23.0. Use the PaymentGateway field instead. |
| Id | NA |
Query |
ID of object. Upon creation of this object, this field becomes Type: zns:ID |
| InvoiceDeliveryPrefsEmail | optional | Create Query Update Delete Filter |
Indicates if the customer wants to receive invoices through email.
Type: boolean |
| InvoiceDeliveryPrefsPrint | optional | Create Query Update Delete Filter |
Indicates if the customer wants to receive printed invoices, such as through postal mail.
Type: boolean |
| InvoiceTemplateId | optional | Create Query Update Delete Filter |
The ID of the invoice template. Each customer account can use a specific invoice template for invoice generation.
Type: zns:ID To find the ID of your current invoice template: In Zuora, navigate to Settings > Z-Billing > Manage Invoice Rules and Templates and click Show Id next to the template you want to use. |
| LastInvoiceDate | optional |
Query |
The date when the previous invoice was generated for the account. The field value is null if no invoice has ever been generated for the account. Type:
Character limit: 29 Version notes: -- Values: automatically generated |
| Name | required | Create Query Update Delete Filter |
Name of the account as displayed in the Zuora UI.
Type: string |
| Notes | optional | Create Query Update Delete Filter |
Comments about the account.
Type: string |
| ParentId | optional | Create Query Update Delete Filter |
Identifier of the parent customer account for this Account object. Use this field if you have customer hierarchy enabled.
Type: zns:ID |
| PaymentGateway | optional | Create Query Update Delete Filter |
Gateway used for processing electronic payments and refunds.
Type: string
|
| PaymentMethodCascadingConsent | optional | Create Query Update Delete |
Indicates whether you have collected consent from your customer to use the Cascading Payment Method feature. Type: boolean |
| PaymentTerm | required | Create Query Update Delete Filter |
Indicates when the customer pays for subscriptions.
Type: string |
| PurchaseOrderNumber | optional | Create Query Update Delete Filter |
The number of the purchase order associated with this account. Purchase order information generally comes from customers.
Type: string |
| SalesRepName | optional | Create Query Update Delete Filter |
The name of the sales representative associated with this account, if applicable.
Type: string |
| SequenceSetId | optional |
Create |
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. Type: string |
| SoldToId |
optional |
Create Query Update Delete Filter |
ID of the person who bought the subscription associated with the account.
Type: zns:ID |
| Status | required | Create Query Update Delete Filter |
Status of the account in the system.
Type: string
|
| TaxCompanyCode | optional | Create Query Update Subscribe |
Unique code that identifies a company account in Avalara. Use this field to calculate taxes based on origin and sold-to addresses in Avalara. This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support. Type: string |
| TaxExemptCertificateID | optional | Create Query Update Delete Filter |
ID of your customer's tax exemption certificate.
Type: string |
| TaxExemptCertificateType | optional | Create Query Update Delete Filter |
Type of the tax exemption certificate that your customer holds.
Type: string |
| TaxExemptDescription | optional | Create Query Update Delete Filter |
Description of the tax exemption certificate that your customer holds.
Type: string |
| TaxExemptEffectiveDate | optional | Create Query Update Delete Filter |
Date when the customer's tax exemption starts.
Type:
Character limit: 29 |
| TaxExemptExpirationDate | optional | Create Query Update Delete Filter |
Date when the customer's tax exemption certificate expires
Type:
Character limit: 29 |
| TaxExemptIssuingJurisdiction | optional | Create Query Update Delete Filter |
Indicates the jurisdiction in which the customer's tax exemption certificate was issued.
Type: string |
| TaxExemptStatus | conditional | Create Query Update Delete Filter |
Status of the account's tax exemption. Required if you use Z-Tax. This field is unavailable if you don't use Z-Tax. Type: string (enum)
|
| TotalInvoiceBalance | NA |
Query |
Total balance of the account's invoices.
Type: decimal (currency) |
| UpdatedById | NA |
Query |
ID of the user who last updated the account.
Type: zns:IDzns:ID |
| UpdatedDate | NA |
Query |
Date when the account was last updated.
Type: dateTime |
| VATId | optional | Create Query Update Delete Filter |
EU Value Added Tax ID. This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support. Type: string |
Additional Field Detail
AccountNumber
The unique account number assigned to the account being created. An Account object must include an AccountNumber value, but you don't have to specify the value.
If you choose not to specify a value for the AccountNumber field when you create an account object, then Zuora assigns a unique account number for you based on the account number prefix specified during setup.
If you choose to specify an AccountNumber value, then you need to use a unique string that doesn't use the account number prefix specified during setup; that prefix is exclusively for Zuora's autopopulation.
You can edit this field until there are posted invoices on the account.
AllowInvoiceEdit
Indicates if associated invoices can be edited. Set to true to allow editing. Set to false or omit the field to prevent editing.
If you omit this field in the following calls, then Zuora uses the default value, false:
AutoPay
Indicates if future payments are automatically collected when they're due during a Payment Run. Set to true to automatically bill. Set to false to or omit the field to prevent automatic billing.
You can only set this value to true when the default payment method is an electronic payment method. If you use the subscribe() call, then you need to pass an electronic method, such as a credit card. If you use the create(account) call, then you need to set the default method to an electronic payment method before you activate the account and before you set the AutoPay value to true.
Batch
A batch organizes your customer accounts into groups to optimize your billing and payment operations. For example, you can create a batch of accounts that are never processed in bill runs because they're canceled, test, or free trial accounts. You can create other batches that group accounts by region or industry.
BillCycleDay
Indicates the account's billing cycle day (BCD), which is when the bill runs generate invoices for the account. To avoid proration charges on the first invoice, set this field to the same day as the account was created.
If you want the BCD to be the end of the month, regardless of the number of days in the month, then set the BillCycleDay value to 31.
For WSDL 30 - 32: Set the value to 0 to automatically set the BCD to the same day as the triggering date of the account's first recurring charge. This auto-set function applies only to recurring charges, not to one-time charges nor usage charges.
For WSDL 33+: If you want to automatically set the BCD to the same day as the triggering date of the account's first recurring charge, then set the optional field, BcdSettingOption to AutoSet, and set the BillCycleDay field to null or to 0.
BillToId
The ID of the person to bill for the account. This value can be the same as the SoldToId value.
If you don't specify a value for this field in a subscribe() call, then Zuora generates the ID from the specified contact.
This field is required for active accounts, but optional for draft accounts.
CommunicationProfileId
Associates the account with a specified communication profile, which is a set of policies that determine how and which notifications are sent to users with the specified communication profile.
Use this field with a subscribe() call for a new subscription.
CreditBalance
The total credit balance for the account. A credit balance represents the total amount of credit that can be applied to future invoices or refunded to a customer. For example, a customer pays for a one-year subscription, but cancels after two months. You can retain the amount the customer paid and allow the customer to use that credit to pay toward another invoice.
CrmId
The CRM account ID for the account. If you create this Account object with a subscribe() call, then you need to return later to set or update this value if you want this field in the account.
A CRM is a customer relationship management system, such as Salesforce.com. The CRM ID is the account ID from that system. If you are using Salesforce.com as your CRM, then Zuora 360 uses the CrmId field value to synchronize information from ZBilling to Salesforce.com.
Id
The ID of this object. Every object has a unique identifier that Zuora automatically assigns upon creation. You use this ID later when you work with the object. For example, if you send an amend() call to modify an existing subscription, then you need to include the specific Subscription object's ID with the call.
The ID for the Account object is AccountId.
InvoiceDeliveryPrefsEmail
Indicates if the customer wants to receive invoices through email.
If you set this value to true, there must be a value for Contact.PersonalEmail or Contact.WorkEmail, otherwise you will receive an error message.
PaymentTerm
Indicates when the customer pays for subscriptions. The field values are defined in the web-based UI on the Define Payment Terms page. Common payment terms are Due Upon Receipt and Net 60, but your specific values depend on your own configuration.
SoldToId
The ID of the person who bought the subscription associated with the account. This value can be the same as the BillToId value.
This field is required for active accounts, but optional for draft accounts.
Status
The status of the account in the system.
Omit this field when you use a subscribe() call, which automatically sets the Status value to Active.
Specify a value for this field when you use a create() call.
Include contact IDs in the BillToId and SoldToId fields when you change the Status value to Active.
Cancel all subscriptions associated with this account before you change the Status value to Canceled. You can't cancel an account that has active subscriptions.
There are a few rules about updating the status of accounts:
- Draft account: You can update a Draft account to Active, assuming the Bill To/Sold To Contacts are assigned.
- Active Account: You can update an Active account to Canceled status only if all subscriptions for the account have been canceled (the subscription's Status is set to Cancelled).
- Cancelled Account: You can update a Canceled account to Active status at any time. However, you cannot update a canceled account to Draft status.
- You cannot update an Active or Cancelled account to Draft.
Some fields can only be updated while the object is still in Draft status. These are noted in the table above with an asterisk (*) next to the word "Update".
Account Number cannot be updated as well when it's associated with an Invoice.
TaxExemptEffectiveDate and TaxExemptExpirationDate
The TaxExemptEffectiveDate and TaxExemptExpirationDate fields exist in Zuora WSDL for backward compatibility with custom implementations accessing Zuora. The fields are not used in the Zuora applications; they do not affect the current integration with payment gateways.
You can use these fields as custom fields in your customization.