Invoices

The Invoice entity describes an Autotask Invoice. In Autotask, Invoices include billing items that have been approved and posted and are being billed to a customer or presented for information purposes only. They are processed through the Autotask Contracts module (Contracts > Invoices). In the API, invoice line items are described by the BillingItems entity.

NOTE  You can refer to the Online Help to find root and child access URLs of the entity you wish to query. Refer to Finding resource and child access URLs of REST API entities for more information.

Entity details

Entity Name: Invoices

Entity Path:

/atservicesrest/v1.0/Invoices
Can Create:  
Can Update:
Can Query:
Can Delete:  
Can Have UDFs:  

Fields that cannot be queried

The following fields from this entity will return an error when queried.

  • dueDate
  • taxRegionID

Conditions and requirements

  • Autotask invoice line items are described by the billingItems entity. To return line items for a specific invoice, query billingItems where billingItems.invoiceID = invoice.ID.
  • To maintain consistency between data submitted via the API and via the UI, invoice.paidDate ignores time stamp information and stores the date only.
  • When using the API with Autotask invoice template variable [Invoice: Number/ID] in HTML output, if invoice.invoiceNumber has a value, then that value will display. If invoice.invoiceNumber has no value, then the Invoice ID displays.
  • If the Multi-currency Installed Module is enabled, the following fields will return the relevant Customer Currency values instead of the Internal Currency values: invoiceTotal and totalTaxValue.

Special endpoints

This entity features special endpoints for querying invoices and exporting them to PDFs.

The InvoiceMarkupXml and InvoiceMarkupHtml endpoints are available for querying invoice information in Autotask.

Calls to these endpoints will return invoice data available from the Autotask UI invoice XML export. The data format is XML or HTML. All XML and HTML results are returned as HTML-encoded strings.

When calling these entities, the syntax you use should resemble the following examples:

https://webservices[n].autotask.net/atservicesrest/v1.0/Invoices/{id}/InvoiceMarkupXML

or

https://webservices[n].autotask.net/atservicesrest/v1.0/Invoices/{id}/InvoiceMarkupHtml

The endpoints will return their results as FileQueryResultModel objects. Refer to The FileQueryResultModel for this object's field definitions.

The InvoicePDF endpoint enables integrations to call and generate invoices as PDF files.

When calling these entities, the syntax you use should resemble the following examples:

https://webservices[n].autotask.net/atservicesrest/v1.0/Invoices/{id}/InvoicePDF

The response will be a 'FileQueryResultModel' that contains the following fields:

  • id: The invoice id contentType: The file type, in this case it will be "application/pdf"

  • fileName: The invoice pdf name

  • fileSize: The size of the invoice pdf file

  • data: The file contents as a byte array

InvoiceMarkup and InvoicePdf query security requirements

By default, the API User (system) (API-only) security level grants Full access permissions, but copies of this security level may have been modified. The API user must have access to the appropriate Autotask module for the entity type and sufficient rights to perform the specified API call.

For details about Autotask custom security levels, refer to the Help topic Create or edit a custom security level.

Field definitions

The following table describes the standard Autotask fields for this entity. Refer to the following articles for more information about working with these fields:

To learn how to query picklist endpoints, refer to Understanding picklists.

Notes

  • For string datatypes, the number in parentheses ( ) indicates the maximum number of characters allowed.
  • LT indicates Local Term.
  • If this entity has child collections, they will appear in a Child collection access URLs or an Entity URLs and relationships drop-down in the Entity details section of this article.
  • You can call the /query/count/ endpoint of a resource to determine how many records a collection holds.

NOTE  This entity includes the webServiceDate field. It allows the external application to flag the date and time that the object is processed. The API provides this field as a convenience for applications that work specifically with the Invoice entity via the REST API. It appears in the Autotask interface as a column on the Invoice History page and can be cleared from the invoice from that page. If an integration uses the webServiceDate to flag an invoice as processed, clearing this field may trigger the integration to re-process the invoice.

Field Name Datatype Read-Only Is Required Reference Name Picklist
batchID integer      
comments string (2000)      
companyID integer   Companies  
createDateTime datetime      
creatorResourceID integer   Resources  
dueDate datetime      
fromDate datetime      
id long    
invoiceDateTime datetime    
invoiceEditorTemplateID integer   InvoiceTemplates  
invoiceNumber string (100)        
invoiceTotal decimal      
isVoided boolean      
orderNumber string (20)      
paidDate datetime        
paymentTerm integer    
taxGroup integer    
taxRegionName string (200)      
toDate datetime      
totalTaxValue decimal      
voidedByResourceID integer   Resources  
voidedDate datetime      
webServiceDate datetime        

Additional resources