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:
- The entityInformation REST API call
- Making basic query calls to the REST API
- Advanced query features of the REST API
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 |