Account
From API Documentation
The Account is the customer's account. This is where Zuora tracks all subscriptions, usage, and transactions for a single account to be billed. Each Account is the source of a recurring invoice stream. Each account must capture everything Zuora needs in order to bill and collect, including "bill to" addresses, payment method and payment method details, payment terms (for example, Net 30), and more.
A new account must be created before a new subscription can be entered.
Using This Object
This object is used to create billing accounts. A billing account contains all of the relevant billing information, including name and billing terms, contacts, payment methods, and subscriptions. A subscription can only be created for an active account. Lastly, invoices are created at the account level and may include all of the charges across many subscriptions for this account.
Fields
| Name | Required? | Type | Allowed Operations: ● Yes ○ No | Allowable Values | Description |
|---|---|---|---|---|---|
| AccountNumber | An account number always exists. Zuora will assign an account number if you do not specify a value. This is different than the ID. | string | ● Create
● Query | This can either be null on insert, which will auto-populate based on the account number prefix specified in setup, or a string value that does not begin with the account number prefix specified in setup. 50 characters maximum. | The account number associated with the account that is being created. This must be unique within your system. Zuora will create an account number if you do not specify a value. If you specify an account number, Zuora uses the number you specify unless it conflicts with an account number already in the system. |
| AdditionalEmailAddresses | No | string | ● Create
● Query | A comma separated list of email addresses. 1200 characters maximum. | Introduced in 7.0 of the API. A list of additional list of email addresses emailed invoices should be sent to. |
| AllowInvoiceEdit | Yes. If you omit this in create(), subscribe() or subscribeWithExistingAccount(), it will default to False. | boolean | ● Create
● Query | True or False | Indicates whether the invoice can be edited (true) or not (false). |
| AutoPay | No. Defaults to false. | boolean | ● Create
● Query | true, false | Set this to true if all future payments are to be automatically billed when due. This can only be set to True if the default payment method is an electronic payment method. For subscribe(), you must pass an electronic payment method like a credit card to set to true. If you use create(Account), you must set the default payment method to an electronic payment method before you can activate the account and have AutoPay set to true.
|
| Balance | No. Read-only field. | double (v1.0-18.0) / decimal (v19.0+) | ○ Create
● Query | Valid currency amount | Current outstanding balance for the account. |
| Batch | Yes | string | ● Create
● Query | Any of the system defined batches (Batch1-Batch20). | This will be validated against the list of batches defined in the system. |
| BcdSettingOption | Yes | string | ● Create
● Query | AutoSet, ManualSet (default) | This field can take the values AutoSet or ManualSet. The default value is ManualSet.
When the value is set to AutoSet, you cannot set the billing cycle day (BCD). The BCD value will be populated automatically by Zuora. |
| BillCycleDay | Yes | int | ● Create
● Query | Any of the system defined bill cycle days (1–30) that have been activated within Z-Billing administration. Specify 0 to set the billing cycle day to "Auto-set" (version 30 and above). Specify 31 to set it to "end of month." | Represents the billing cycle day (BCD) for the account, and when billing runs generate invoices for this account. Usually set based to the same day the account was created to avoid any proration charges on first invoice. Set the value to 31 to indicate "end of month."
Set the value to 0 to set the value to use the auto-set functionality. This allows the account BCD to be set to the same day as the triggering date of the first recurring charge on the account. This only applies to recurring charges, and not to one-time or usage charges. See Customer Accounts: Bill Cycle Day for more information. |
| BillToId | Required for active accounts. Draft accounts are allowed to not have a BillToId. | zns: ID | ● Create
● Query | A valid contact ID created for this account. Not specified in subscribe() or subscribeWithExistingAccount(), rather it Zuora will generate the ID from the Contact specified. | This is the ID of the person who is to be billed for the subscription. It can be the same as the SoldToId, though it doesn't have to be. |
| CommunicationProfileId | No | zns:ID | ● Create
● Query | The ID of a communication profile. | When creating a new account or updating an existing customer account, set CommunicationProfileId to a specific profile ID. See Setup Profiles, Notifications, and Templates for more information about using communication profiles. You can set the communication profile field from a subscribe call when creating a new subscription. See CommunicationProfile for information about the CommunicationProfile object. |
| CreatedById | System generated, always exists | zns: ID | ○ Create
● Query | This field is not editable. 32 characters maximum. | The Zuora system automatically generates this Id of the user who created the object. |
| CreatedDate | System generated, always exists | dateTime | ○ Create
● Query | This field is not editable. | The Zuora system automatically generates this, and denotes when the objects was first created. |
| CreditBalance | No (system generated if enabled) | decimal | ○ Create
● Query | Displays the total credit balance for the account. Available in version 22.0, and must be enabled for the tenant. | |
| CrmId | No | string | ● Create
● Query | 100 characters maximum | The CRM account ID. You can create an initial subscription using the API, and later return with another call to set or update the CrmId field in this object. |
| Currency | Yes | string | ● Create
● Query | Allowable values are defined in the Admin interface. | The currency with which the account is being paid. |
| CustomerServiceRepName | No | string | ● Create
● Query | 50 characters | The name of this account's Customer Service representative. The customer may choose to supply this information if a Customer Service representative was involved. |
| DefaultPaymentMethodId | Yes if AutoPay is set to Yes; No otherwise | zns: ID | ● Create
● Query | ID of existing payment method on Account | A reference to the default payment for this account. |
| Gateway | No | string | ● Create
● Query | Valid name of a configured gateway | Deprecated with version 23.0, and has been renamed PaymentGateway. Specifies which gateway to use to process electronic payments and refunds. |
| InvoiceDeliveryPrefsEmail | No. | boolean | ● Create
● Query | True or False. Defaults to false. | Specifies whether the customer prefers to receive an invoice via email.
You cannot set this value in |
| InvoiceDeliveryPrefsPrint | No | boolean | ● Create
● Query | True or False. Defaults to false. | Specifies whether the customer prefers to receive a printed version of the invoice (typically via postal mail). You can download the PDF invoice for print from the invoice detail page or from the bill run. |
| InvoiceTemplateId | No | zns: ID | ● Create
● Query | ID of template to be used for generating invoices. | A reference to the invoice template. This allows each customer account to use a specific invoice template for invoice generation. |
| LastInvoiceDate | No, read-only | dateTime | ○ Create
● Query | This field is system generated and not editable. | The date when the last invoice was generated for an account. The field is NULL if no invoice has ever been generated for the account. |
| Name | Yes | string | ● Create
● Query | 50 characters | This is the name of the account. |
| Notes | No | string | ● Create
● Query | 65535 characters maximum | A field to use to record notes relating to the account. |
| ParentId | No | zns: ID | ● Create
● Query | The ID of the parent account. | If you have customer hierarchy enabled, you can use this to define a parent customer account for an account. |
| PaymentGateway | No | string | ● Create
● Query | Valid name of a configured gateway | Replaces the field Gateway as of version 23.0. Specifies which gateway to use to process electronic payments and refunds. Inherits the default set in Payment Settings if you do not specify a value. |
| PaymentTerm | Yes | string | ● Create
● Query | Typical payment terms (e.g., Due Upon Receipt, Net 30, Net 45, etc.) | This field maps to the payment terms defined for your organization as configured in administrative settings. If a value is provided, it will be referenced with the list of supported payment terms. |
| PurchaseOrderNumber | No | string | ● Create
● Query | Any text string, 100 characters maximum | The number of the purchase order associated with this account. |
| SalesRepName | No | string | ● Create
● Query | 50 characters maximum | The customer may choose to supply this information based on whether a sales rep was involved. |
| SoldToId | Required for active accounts. Draft accounts are allowed to not have a SoldToId. | zns:ID | ● Create
● Query | A valid contact ID created for this account | This is the ID of the person who the subscription is being sold to. It can be the same as the BillToId, though it doesn't have to be. |
| Status | Not required in subscribe() call, which will automatically create an active account. Required for create() call. | string (enum) | ● Create
● Query | Draft, Active, or Canceled | The status of the account. The values are case sensitive and must be used exactly as shown here. |
| TaxExemptCertificateId | No. Only available to customers of Z-Tax. | string | ● Create
● Query | Any string, can be null. 32 characters maximum. | The ID/identifier of the tax exemption certificate. |
| TaxExemptCertificateType | No. Only available to customers of Z-Tax. | string | ● Create
● Query | Any string, can be null. 32 characters maximum. | This is a freeform field that allows you to identify the type of tax exemption certificate. |
| TaxExemptDescription | No. Only available to customers of Z-Tax. | string | ● Create
● Query | Any string, can be null. 500 characters maximum. | Free form field to describe the tax exemption. |
| TaxExemptEffectiveDate | No. Only available to customers of Z-Tax. | dateTime | ● Create
● Query | A valid datetime stamp. | The date on which the account becomes tax exempt. |
| TaxExemptExpirationDate | No. Only available to customers of Z-Tax. | dateTime | ● Create
● Query | A valid date | The date on the account on which the tax exemption status ends. |
| TaxExemptIssuingJurisdiction | No. Only available to customers of Z-Taxation. | string | ● Create
● Query | Any string, can be null. 32 characters maximum. | A freeform field used to describe the jurisdiction of the tax exemption issuing authority/jurisdiction. |
| TaxExemptStatus | Yes (if using Z-Taxation) | string | ● Create
● Query | Yes, No, PendingVerification. | The status of the tax exemption for the account. |
| TotalInvoiceBalance | No. Only applicable/available to customers using Credit Balances. | decimal | ○ Create
● Query | Total balance of this customer account's invoices | |
| UpdatedById | System generated, always exists | zns:Id | ○ Create
● Query | This field is not editable. 32 characters maximum. | The Zuora system automatically generates this Id of the user who last updated the object. |
| UpdatedDate | System generated, always exists | dateTime | ○ Create
● Query | This field is not editable. | The Zuora system automatically generates this, and denotes when the objects was last updated. |
