Document types

AvaTax supports various transaction types, such as sales, purchases, returns (refunds or reverse transactions), and inventory transfers. Each transaction type is available in two forms:

Invoice form: A permanent transaction stored and reported to the tax authority.
Order form: A temporary estimate.

These forms result in the following transaction types:


Transaction type	Lifetime	Description
`SalesInvoice`	Permanent	A finalized sale made to a customer
`SalesOrder`	Temporary	A quote for a potential sale
`PurchaseInvoice`	Permanent	A purchase made from a vendor
`PurchaseOrder`	Temporary	A quote for identifying estimated tax to pay to a vendor
`ReturnInvoice`	Permanent	A finalized refund given to a customer
`ReturnOrder`	Temporary	A quote for a refund to a customer
`InventoryTransferInvoice`	Permanent	A finalized shipment of inventory from one location to another
`InventoryTransferOrder`	Temporary	An estimate for shipping inventory from one location to another

AvaTax uses the type field to differentiate between these types of transactions. If you forget to include the type field in the CreateTransaction API, AvaTax will assume that you want a temporary estimate and will set a value of SalesOrder, which won’t be recorded in AvaTax.

Many connectors will only ever work with sales transactions; but if you’re developing a plugin for an accounting system, expect to handle all different types of transactions. Let's discuss how each of these types is different.

Orders vs. invoices

Customers often need to estimate tax for a transaction and record the actual tax for that transaction. AvaTax supports both scenarios:

Use AvaTax to predict taxes before taking action, such as showing "Estimated Tax" on a web storefront.
Use AvaTax to calculate taxes at the moment the transaction occurs, such as recording a sale in an accounting system.

In AvaTax:

An Order represents a temporary transaction that isn’t saved.
An Invoice represents a permanent transaction that will be maintained.

In AvaTax, an “Order” represents a temporary transaction that isn’t saved, whereas an “Invoice” represents a permanent transaction that will be maintained. Think about these documents like you’re a salesperson:

Because every type of transaction must be able to follow this same pattern, AvaTax supports all transaction types as both orders and invoices. Quotes and sales orders tend not to reflect actual sales and can often be abandoned (without a void or return processed). For this, we recommend using a document type of SalesOrder. Invoices usually represent an actual sale, so you can use a document type of SalesInvoice. Because the creation of an invoice doesn’t usually represent the finalization of that sale, keep the document in an uncommitted status.

When the invoice is posted and the sale is recognized, the document should be committed by setting commit=true for the transaction or when adjusting a transaction. You can use committing only for invoice document types.

Returns and credit memos work just like invoices, but they’re sent with negative amounts and some date considerations. If invoices or returns are voided, that cancellation needs to be communicated to AvaTax.

It’s worth noting that the invoice transaction types provide a key compatibility between Avalara’s tax calculation API and the Avalara Managed Returns Service. The Managed Returns Service supports filing taxes calculated with AvaTax, but you can only file taxes that were recorded using invoice types. Anything you calculated using an order type is considered a temporary estimate and won’t be reported.

Because order transaction types are temporary documents, it’s also worth noting that your transaction won’t be retrievable later. All order transactions will have ID numbers that are -1, indicating that they can't be fetched back using the API. Invoice transactions have positive ID numbers and can be retrieved back.

Next, let’s describe the various types of transactions and see how they work.

Sales transactions

A SalesOrder or SalesInvoice transaction represents a sale that your company made to a customer. This is by far the most common type of transaction that AvaTax handles. As discussed, a SalesOrder is an estimate and a SalesInvoice is a record of a transaction that occurred.

Sales transactions are expected to be recorded as they occur. For example, if you calculate an estimate for a customer using a SalesOrder on the 11th of the month, then convert it to a SalesInvoice on the 20th of the month, choose the transaction date as the 20th. The AvaTax API supports this date behavior natively - just provide the date field on the CreateTransaction API, and AvaTax will record your transaction on that date.

Return transactions

When a customer changes their mind and asks for a refund, you can process that refund by specifying a ReturnOrder or ReturnInvoice transaction, or you can call the RefundTransaction API. This transaction type refers to a reversal of the charges that occurred when you originally made the sale. As usual, the ReturnOrder can be used for estimating and the ReturnInvoice is a permanent record.

Unlike sales transactions, return transactions have two dates. The first date indicates when the return occurred, and the second date is the date when the original purchase was made. Two dates are needed because the tax rate may have changed since the customer made the original purchase! Here’s how to refund the customer the exact amount they paid originally:

Purchase transactions

A purchase transaction represents a purchase made by your company to a vendor. A PurchaseOrder represents a quote that you request from a vendor, and a PurchaseInvoice represents a finalized purchase transaction.

In the United States, most vendors automatically charge and pay transaction taxes on your behalf. However, some companies choose to use AvaTax to identify any discrepancies between the tax rate you were charged by a vendor and the correct tax rate for a product or service. This calculation can assist a company in recovering overpaid taxes or in identifying any cases where their vendor relationships aren't in full compliance with tax laws.

Use a PurchaseOrder to get an estimate of the tax that you’ll pay on a transaction, and use a PurchaseInvoice to record a transaction that occurred. When reporting a PurchaseInvoice, specify the tax amount that the vendor charged you, and have Avalara calculate the actual tax discrepancy. This allows you to correctly report Consumer Use Tax via Avalara’s Managed Returns Service.

Inventory transfer transactions

Inventory transfers provide another way of tracking transactions that have Consumer Use Tax implications. For companies with multiple warehouses and offices, shifting inventory from one location to another can have tax implications.

As with the other document types, an InventoryTransferOrder represents an estimate, and an InventoryTransferInvoice represents a permanent transaction.