Invoice
An invoice represents a bill to a customer. You generate invoices from a bill run, then email them as PDFs to your customers in batches or individually, or print them and send them to customers through postal mail. You can also generate a preview of an invoice before you activate a new subscription or amendment.
The Invoice object provides information about customers' accounts for invoices, including dates, status, and amounts. It is created at the account level, and can include all of the charges for multiple subscriptions for an account.
Supported calls
You can use this object with the following calls:
- generate()
- update()
- delete() (WSDL 11.0+)
- query()
Walkthroughs and use cases
Here are some sommon ways to use this object:
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 |
|---|---|---|---|
|
AccountId |
Required |
Query |
The account ID. Type: zns:ID Character limit: 32 Version notes: -- Values: inherited from |
|
AdjustmentAmount |
optional |
Query |
The amount of the invoice adjustments associated with the invoice. Type: decimal (currency) Character limit: 16 Version notes: WSDL 20.0+ Values: a valid currency amount |
|
Amount |
optional |
Query |
The sum of all charges and taxes associated with the invoice. Type: decimal (currency) Character limit: 16 Version notes: type is double for WSDL 18.0 and older Values: automatically generated |
|
AmountWithoutTax |
optional |
Query |
The sum of all charges associated with the invoice. Taxes are excluded from this value. Type: decimal (currency) Character limit: 16 Version notes: Z-Tax; type is double for WSDL 18.0 and older Values: automatically generated |
| AutoPay | optional |
Update |
Whether invoices are automatically picked up for processing in the corresponding payment run. By default, invoices are automatically picked up for processing in the corresponding payment run. Type: boolean Character limit: 5 Version notes: WSDL 89.0+ Values: automatically generated from one of the following: |
|
Balance |
optional |
Query |
The remaining balance of the invoice after all payments, adjustments, and refunds are applied. Type: decimal (currency) Character limit: 16 Version notes: type is double for WSDL 18.0 and older Values: automatically generated |
|
BillRunId
|
optional |
Query |
The ID of a Bill Run. Type: string Character limit: 32 Version notes: Available from WSDL 66.0 and above Values: a BillRun ID |
| BillToContactId | optional | Query Filter |
The ID of the bill-to contact associated with the invoice. Type: zns:ID Character limit: 32 Version notes: WSDL 118.0+ Values: automatically generated |
| BillToContactSnapshotId |
optional |
Query |
The ID of the Bill To contact snapshot. Type: zns:ID Character limit: 32 Version notes: WSDL 85.0+ Values: automatically generated |
| Body | optional | Query Filter |
A PDF that contains the contents of the invoice. See Query an Invoice Body Field for the steps to query the Body field content. Type: string Character limit: -- Version notes: WSDL 2.0+ |
|
Comments |
optional |
Query |
Additional information related to the invoice that a Zuora user added to the invoice. Type: string Character limit: 255 Version notes: WSDL 20.0+ Values: a string of 255 characters or fewer |
|
CreatedById |
optional |
Query |
The user ID of the person who created the invoice. If a bill run generated the invoice, then the value is the user ID of person who created the bill run. Type: zns:ID Character limit: 32 Version notes: WSDL 20.0+ Values: automatically generated |
|
CreatedDate |
optional |
Query |
The date when the invoice was generated. Type: dateTime Character limit: 29 Version notes: WSDL 20.0+ Values: automatically generated |
|
CreditBalanceAdjustmentAmount |
optional |
Query |
The currency amount of the adjustment applied to the customer's credit balance. Type: decimal (currency) Character limit: 16 Version notes: WSDL 22.0+ Values: a valid currency amount This field is only available if the Credit Balance feature is enabled on your tenant. Contact Zuora Global Support to enable this feature. |
| Currency | optional | Query |
The currency displayed in an invoice. Type: string Version notes: WSDL 147.0+ Values: currency code |
|
DueDate |
required |
Query |
The date by which the payment for this invoice is due. Type:
Character limit: 29 Version notes: -- |
|
optional |
Query |
The ID of this object. Upon creation, the ID for this object is InvoiceId. Type: zns:ID Character limit: 32 Version notes: -- Values: automatically generated |
|
|
IncludesOneTime |
optional |
Create |
Specifies whether the invoice includes one-time charges. You can use this field only with the Type: boolean Character limit: 5 Version notes: WSDL 11.0+ Values: automatically generated from one of the following: |
|
IncludesRecurring |
optional |
Create |
Specifies whether the invoice includes recurring charges. You can use this field only with the Type: boolean Character limit: 5 Version notes: WSDL 11.0+ Values: automatically generated from one of the following: |
|
IncludesUsage |
optional |
Create |
Specifies whether the invoice includes usage charges. You can use this field only with the Type: boolean Character limit: 5 Version notes: WSDL 11.0+ Values: automatically generated from one of the following: |
|
InvoiceDate |
optional |
Create |
Specifies the date on which to generate the invoice. Type:
Character limit: 29 Version notes: -- |
|
InvoiceNumber |
optional |
Query |
The unique identification number for the invoice. This number is returned as a string. Type: sequence Character limit: 32 Version notes: -- Values: automatically generated |
|
LastEmailSentDate |
optional |
Query |
The date when the invoice was last emailed. Type: dateTime Character limit: 29 Version notes: -- Values: automatically generated |
|
PaymentAmount |
optional |
Query |
The amount of payments applied to the invoice. Type: decimal (currency) Character limit: 16 Version notes: WSDL 20.0+ Values: automatically generated |
| PaymentTerm | optional | Query Filter |
The name of the payment term associated with the invoice. Type: decimal (currency) Character limit: 100 Version notes: WSDL 118.0+ Values: automatically generated |
|
PostedBy |
optional |
Query |
The user ID of the person who moved the invoice to Posted status. Type: zns:ID Character limit: 32 Version notes: -- Values: automatically generated |
|
PostedDate |
optional |
Query |
The date when the invoice was posted. Type: dateTime Character limit: 29 Version notes: -- Values: automatically generated |
|
optional |
Query |
Specifies the amount of a refund that was applied against an earlier payment on the invoice. Type: decimal (currency) Character limit: 16 Version notes: -- Values: automatically generated |
|
|
RegenerateInvoicePDF |
optional |
Update |
Regenerates a PDF of an invoice that was already generated. Add this field to an For one specific invoice, you can use this field to regenerate PDF files for a maximum of 100 times. Note that when you set the "When field RegenerateInvoicePDF is set to true to regenerate the invoice PDF file, changes on other fields of the invoice are not allowed." Type: boolean Character limit: 5 Version notes: WSDL 40.0+ Values: |
|
Source |
optional |
Query |
Specifies the source of the invoice. This field is in controlled release. Type: string (enum) Character limit: 15 Version notes: -- Values: API, BillRun, CustomerInvoice |
|
SourceId |
optional |
Query |
The ID of the value in the Source field. This field is in controlled release. Type: zns:ID Character limit: 32 Version notes: -- Values: |
|
SourceType |
optional |
Query |
The type of the invoice source. Type: string (enum) Character limit: 16 Version notes: WSDL 118.0+ Values: |
|
optional |
Query |
The status of the invoice in the system. This status is not the status of the payment of the invoice, just the status of the invoice itself. Type: string (enum) Character limit: 8 Version notes: -- Values: one of the following:
|
|
| SoldToContactSnapshotId |
optional |
Query |
The ID of the Sold To contact snapshot. Type: zns:ID Character limit: 32 Version notes: WSDL 85.0+ Values: automatically generated |
|
TargetDate |
required |
Create |
This date is used to determine which charges are to be billed. All charges that are to be billed on this date or prior will be included in this bill run. Type:
Character limit: 29 Version notes: -- |
|
TaxAmount |
optional |
Query |
The total amount of the taxes applied to the invoice. Type: decimal (currency) Character limit: 16 Version notes: requires Z-Tax, WSDL 20.0+ Values: automatically generated |
|
TaxExemptAmount |
optional |
Query |
The total amount of the invoice that is exempt from taxation. Type: decimal (currency) Character limit: 16 Version notes: requires Z-Tax, WSDL 20.0+ Values: automatically generated |
| TaxStatus | optional | Query Filter |
The status of tax calculation related to the invoice. Type: string (enum) Character limit: - Version notes: 100 and later Values: one of the following:
Note: Taxes will be applied for external tax integrations like direct Avalara and tax connectors to gather tax outcomes and messages and do not apply to Zuora tax. |
| TaxMessage | optional | Query Filter |
The message about the status of tax calculation related to the invoice. If tax calculation fails in one invoice, this field displays the reason for the failure. Type: string Character limit: 1000 Version notes: 100 and later Values: automatically generated |
|
optional |
Query |
Specifies whether or not the invoice was transferred to an external accounting system, such as NetSuite. Note: You can only edit this field if the invoice is posted. Editing this field for draft invoices is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support. Type: string (enum) Character limit: 10 Version notes: WSDL 26.0+ Values: Processing, Yes, Error, Ignore |
|
|
UpdatedById |
optional |
Query |
The ID of the user who last updated the invoice. Type: zns:ID Character limit: 32 Version notes: -- Values: automatically generated |
|
UpdatedDate |
optional |
Query |
The date when the invoice was last updated. Type: dateTime Character limit: 29 Version notes: -- Values: automatically generated |
Additional Field Detail
Comments
Additional information related to the invoice that someone added to the invoice.
This field is read-only in the API. You can add comments in the web-based UI to invoices in Draft status. You can't change or add comments to an invoice in any status other than Draft.
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 Invoice object is InvoiceId.
RefundAmount
Specifies the amount of a refund that was applied against an earlier payment on the invoice. This read-only field is generated by the system, and exists only when a payment that was applied to an invoice is later refunded.
The formula is Amount - Payments + Adjustments - Applied Credit Balance = Balance.
For example: An invoice is generated for $1000. An $800 payment is applied, then $300 of that payment is refunded. In this example, the amount of the invoice (Invoice.Amount) is $1000, the balance (Invoice.Balance) is $500 (= $1000-$800+$300), the refund amount (Invoice.RefundAmount) is $300, and the payment amount (Invoice.PaymentAmount) is $800.
Status
The status of the invoice in the system. This status is not the status of the payment of the invoice, just the status of the invoice itself.
When you initially create an invoice, if the invoice generating process takes longer, the status is Generating. Once the invoice is generated, the status is changed to Draft.
During the invoice generation process, there are cases where a temporary invoice with the prefix "TMP-" is generated. The temporary invoice is automatically deleted once the invoice generation process is complete.
You can change the status of a Draft invoice to Posted to post the invoice or to Canceled to cancel the invoice. Changing the status of the invoice moves the invoice along in the system.
TransferredToAccounting
Specifies whether or not the invoice was transferred to an external accounting system, such as NetSuite. You can specify one of the following values:
ProcessingYesErrorIgnore
You can't specify the value No, in the API, but can specify No in the web-based browser UI. To set this value to No, use the web-based browser UI.