Knowledge Center

Knowledge Center > API > SOAP API > SOAP API Object Reference > Invoice

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, the 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:

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
Filter

The account ID.

Type: zns:ID

Character limit: 32

Version notes: --

Values: inherited from Account.ID for the invoice owner

AdjustmentAmount

optional

Query
Filter

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
Filter

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
Filter

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

Balance

optional

Query
Filter

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
Filter

The ID of a Bill Run.

Type: string


Character limit: 32

Version notes: Available from WSDL 66.0 and above

Values: a BillRun ID

BillToContactSnapshotId

optional

Query
Filter

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
Filter

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
Filter

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
Filter

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.

DueDate

required

Query
Filter

The date by which the payment for this invoice is due.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29

Version notes: --

Id

optional

Query
Filter

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
Query
Delete
Filter

Specifies whether the invoice includes one-time charges. You can use this field only with the generate() call for the Invoice object.

Type: boolean

Character limit: 5

Version notes: WSDL 11.0+

Values: automatically generated from one of the following: True (default), False

IncludesRecurring

optional

Create
Query
Delete
Filter

Specifies whether the invoice includes recurring charges. You can use this field only with the generate() call for the Invoice object.

Type: boolean

Character limit: 5

Version notes: WSDL 11.0+

Values: automatically generated from one of the following: True (default), False

IncludesUsage

optional

Create
Query
Delete
Filter

Specifies whether the invoice includes usage charges. You can use this field only with the generate() call for the Invoice object.

Type: boolean

Character limit: 5

Version notes: WSDL 11.0+

Values: automatically generated from one of the following: True (default), False

InvoiceDate

optional

Create
Query
Delete
Filter

Specifies the date on which to generate the invoice.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29

Version notes: --

InvoiceNumber

optional

Query
Filter

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
Filter

The date when the invoice was last emailed.

Type: dateTime

Character limit: 29

Version notes: --

Values: automatically generated

PaymentAmount

optional

Query
Filter

The amount of payments applied to the invoice.

Type: decimal (currency)

Character limit: 16

Version notes: WSDL 20.0+

Values: automatically generated

PostedBy

optional

Query
Filter

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
Filter

The date when the invoice was posted.

Type: dateTime

Character limit: 29

Version notes: --

Values: automatically generated

RefundAmount

optional

Query
Filter

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 update() call to regenerate an invoice PDF.

Note that when you set the RegenerateInvoicePDF field to true, you cannot update any other fields in the same update() call. Otherwise, you will receive the following INVALID_VALUE error:

"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: True, False

Source

optional

Query
Filter

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
Filter

The ID of the value in the Source field.

This field is in controlled release.

Type: zns:ID

Character limit: 32

Version notes: --

Values:

Status

optional

Query
Update
Filter

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:

  • Draft (default, automatically set upon invoice creation)

  • Posted

  • Canceled

SoldToContactSnapshotId

optional

Query
Filter

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
Query
Filter

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

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29

Version notes: --

TaxAmount

optional

Query
Filter

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
Filter

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

TransferredToAccounting

optional

Query
Update
Filter

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
Filter

The ID of the user who last updated the invoice.

Type: zns:ID

Character limit: 32

Version notes: --

Values: automatically generated

UpdatedDate

optional

Query
Filter

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, its default status is Draft. 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:

  • Processing
  • Yes
  • Error
  • Ignore

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.

Last modified

Tags

Classifications

(not set)