Planning your ecommerce integration

This section provides an overview of the Sales Tax badge requirements that you need to meet in order to become a certified ecommerce partner. Review this section to help you plan your integration.

Advice: You may notice that some parameters are considered optional by the API documentation; however these parameters are required for certification. For example if you omit a 'code' in the create transaction request, AvaTax will generate a UUID. However for certification, we are expecting your transaction identifier to be passed in this field.

Administration and utilities

This section describes the requirements for the settings window of your integration.

Requirement	Use Case	Endpoints	Required/Conditional/Suggested
AvaTax configuration window	Merchants/users need to be able to access a URL that points to AvaTax and log in using either their username/password or their account number/license key. They also need to be able to perform a company code lookup.	QueryCompanies	Required
Test AvaTax connection	Merchants/users need to be able to test the connection to the AvaTax service and verify their AvaTax credentials.	Ping, QueryCompanies	Required
Disable document recording	In order for this connector to be used in conjunction with other integrations, merchants/users must be able to control which connector is used for recording (committing) documents to AvaTax.	CreateTransactionModel > Type	Required
Option to disable AvaTax	Merchants/users must have the option to turn on or off the AvaTax Calculation service, independent of any other Avalara product or service. For example, a customer does not agree with the amount of tax that AvaTax calculated, they can turn off this calculation and post using their own calculated tax.	N/A	Required
Option to enable client-side logging	Merchants/users must have the option to retrieve detailed AvaTax transaction logging within the application, including the capture of round-trip processing time, and they need the complete request/response for each call made to Avalara services. This logging does not need to run all the time, as doing so will cause the database to grow unnecessarily large. This can be set up to only log the last week, 30 days, custom, or have a control for the next N hours, etc. This requirement is to assist customers and support in troubleshooting exercises, so it must be retrievable by an end user (or an administrator). It should be specifically Avalara service calls.	N/A	Required
User guide implementation	Merchants/users must have a way to access a User Implementation Guide. This guide should contain screenshots and information allowing the end user to configure for AvaTax, including where the company code is entered, where the credentials are entered, and where tax codes can be mapped within the application.	N/A	Required
Address validation implementation	Merchants/users must have a way to validate addresses entered into AvaTax. This can be implemented using Avalara's address validation service or some other service.	ResolveAddressPost or some other third-party validator	Required
Display prices with tax included	Merchants/users may need to be able to show prices in transactions with the tax included. They can do this by enabling the `taxIncluded` parameter in the line level of the `CreateTransaction` model. This is required for a VAT badge.	LineItemModel	Conditional. This is required for a VAT badge.
Request timeout definition	Merchants/users should define a timeout length on their backend service for API requests in AvaTax.	N/A	Suggested

Customer record integration

This section describes the requirements for setting up your customers.

Requirement	Use Case	Endpoints	Required/Conditional/Suggested
Customer code input	Merchants/users must be able to input a case-sensitive and unique customer code (number, ID) that will be passed to the AvaTax service. Codes must be no more than 50 characters.	GetCustomer	Required
Entity use code input	Merchants/users must be able to input a group of codes that indicate the type of exemption. These can be standard codes as well as custom codes. It is best to manage this value in your application’s Customer record and pass it to AvaTax as `entityUseCode` at either the document or line level, whichever is applicable.	ListEntityUseCodes CreateTransactionModel	Required
Exemption number	Merchants/users should be able to include an exemption number at the customer level for tracking those customers who have tax exempt transactions.	CreateCertificate	Suggested
Line-level exemptions	Merchants/users should be able to identify individual items on a transaction as exempt from tax. This allows merchants to sell a mixture of exempt and non-exempt items in a single transaction.	LineItemModel	Suggested
Line-level exemption override	Merchants/users should be able to enter a taxable line item on a transaction for an otherwise exempt customer.	LineItemModel	Suggested
Ship-to address exemption	Merchants/users should be able to identify individual customer ship-to locations as Exempt, separate from the customers default address.	N/A	Suggested

Item/charge integration

This section describes requirements for how you define what you're selling and how those items are associated with items in AvaTax.

Requirement	Use Case	Endpoints	Required/Conditional/Suggested
Item code	Merchants/users must be able to specify a unique item code that is passed to AvaTax. Items can be a maximum of 50 characters.	ItemModel	Required
Item description	Merchants/users must be able to input a human-readable description for each `ItemCode` in their product catalog.	ItemModel	Required
AvaTax tax code mapping - Item/SKU	Merchants/users must be able to associate an item or item group to an AvaTax Tax Code to describe the taxability (for example, "Clothing-Shirts" – "B-to-C").	ListTaxCodes	Required
Non-standard items	Merchants/users must have a way of associating Freight/Shipping and/or Handling charges to an AvaTax Tax Code to describe the taxability.	ItemModel	Required
Tax code mapping group	Merchants/users should be able to assocate a group of items to an AvaTax Tax Code in order to describe the taxability of the group.	N/A	Suggested
Tax code lookup	Merchants/users should be provided with a method for looking up tax codes.	ListTaxCodes	Suggested

Sales/billing document integration

This section describes requirements for how information is passed from an invoice or a quote.

Requirement	Use Case	Endpoints	Required/Conditional/Suggested
Document code	Merchants/users must have a way to enter a document code in order to tie transactions in AvaTax to the transactions in their underlying system.	CreateTransactionModel	Required
Customer code	Merchants/users must have a way to specify a customer code that can be used to identify any certificates linked to the customer.	CreateTransactionModel	Required
Document dates	Merchants/users must be able to specify the calendar date when a transaction occurs.	CreateTransactionModel	Required
Tax calculation date	Merchants/users must be able to override the date used to calculate tax.	TaxOverrideModel	Required
Document type	Merchants/users must be able to specify the type of document that I am creating in a transaction.	CreateTransactionModel	Required
Header level destination address	Merchants/users must be able to specify the ship-to address for an entire transaction.	AddressModel	Required
Header level origin address	Merchants/users must be able to specify the ship-from address for an entire transaction.	AddressModel	Required
Line number	Merchants/users must be able to include multiple lines on a transaction, with each line specified using a unique line number.	LineItemModel	Required
Item code	Merchants/users must be able to specify an item code for each line in a transaction in order to associate a tax code for that item.	LineItemModel	Required
Item description	Merchants/users must be able to include a description of an item on each line of a transaction. For SST, this description must be human readable.	LineItemModel	Required
Quantity	Merchants/users must be able to specify the quantity of an item for each line of a transaction.	LineItemModel	Required
Amount (extended)	Merchants/users must be able to specify the total amount (net currency value) for each line item in a transaction.	LineItemModel	Required
Tax code	Merchants/users must be able to specify a tax code for each line item in a transaction.	LineItemModel	Required
Verify Avalara calcaluted Tax Amount is used in transaction	Merchants/users must ensure that the Tax Amount value from a transaction response is used to populate the tax field in the integration.	N/A	Required
Freight items must be transmitted separately	Merchants/users must have a way to specify shipping and freight charges on a separate line in each transaction.	N/A	Required
Determination call - Sales Order/Sales Invoice	Merchants/users must ensure that sales documents are processed through a logical document lifecycle.	N/A	Required
PostTax/CommitTax call - Invoices	Merchants/users must determine when to record (commit) a transaction in the AvaTax account and also ensure that invoices are reported properly.	N/A	Required
Send discounts appropriately	Merchants/users must ensure that discounts on transactions are processed appropriately.	CreateTransactionModel LineItemModel	Required
Location code	Merchants/users may be required to allow users to specify a reporting location code in transactions. This is required if the application supports multiple "origin" addresses.	CreateTransactionModel	Conditional. This is required if the application supports multiple origin addresses.
Exemption number	Merchants/users may be required to provide a way for users to specify an exemption number at the header level of a transaction.	CreateTransactionModel	Conditional. This is required if the application does not support Customer Usage Type/Entity Use Code exemptions.
Voiding/deleting invoices	If the merchant's source application supports voiding/deleting invoices, then they must allow users to void/delete invoices in AvaTax.	VoidTransactionModel	Conditional. This is required if the source application supports voiding/deleting invoices.
Include Point of Order Origin in determination request	If the merchant's source application supports a Point of Order Origin address, then they must provide this option to users in AvaTax.	AddressModel	Conditional. This is required if the source application supports a Point of Order Origin address.
Include Point of Order Acceptance in determination request	If the merchant's source application supports a Point of Order Acceptance address, then they must provide this option to users in AvaTax.	AddressModel	Conditional. This is required if the source application supports a Point of Order Acceptance address.
Send location code with the transaction	If the merchant's source application supports multiple origin addresses, then they must provide an option for users to specify a reporting location code in the determination request.	CreateTransactionModel	Conditional. Required if the source application supports multiple origin addresses.
Point of Order Origin - header level	Merchants/users should be able to specify the address of the place of business where the customer's order is received and should be able to include this at the document header level.	AddressModel	Suggested
Point of Order Acceptance - header level	Merchants/users should be able to specify the address of the place of business where the customer's order is accepted/approved and should be able to include this at the document header level.	AddressModel	Suggested
Exemption override	Merchants/users should be able to override an entire exempt transaction or individual exempt line items on a transaction and mark them as taxable.	LineItemModel	Suggested
Line-level addresses	Merchants/users should be able to specify the ship-to, ship-from, point or order origin, and point of order acceptance address for each line in a transaction.	AddressModel	Suggested
Send optional header-level data elements - Purchase Order number	Merchants/users should be able to specify a purchase order number for a transaction.	CreateTransactionModel	Suggested
Send optional line-level data elements - Entity/Use code	Merchants/users should be able to specify an entity/use code for each line item in a transaction.	LineItemModel	Suggested
Latitude/Longitude support	Merchants/users should be able to pass latitude and longitude values into each address type to pinpoint that address by geo location. This is supported for US addresses only.	AddressModel	Suggested

Server and installation requirements

This section provides requirements for including calls made from the integration and demonstrating/documenting the software installation process.

Requirement	Use Case	Endpoints	Required/Conditional/Suggested
Pass connector identifier information via the TaxSvc.ProfileClient property	Merchants/users must include information about the connection as a signature in each transaction.	N/A	Required
Reasonable errrors on server-side analysis	Merchants/users must ensure that the implementation does not include errors except those that would result from normal (but invalid) user input (for example, invalid address data). In addition, these errors must be logged/displayed appropriately in the application.	N/A	Required
Reasonable ratio of tax determination and address validation calls to committed documents	Merchants/users must ensure that the integration minimizes traffic. AvaTax will expect to see up to approximately 10 calculations per finalized document (including for abandonded carts). Failing to do so will drive up usage and billing. Note that you can also provide a simple "estimated tax" option, just ensure that the estimate does not call to AvaTax.	N/A	Required
Demonstrate and document installation of software	If there is something to install on the soure application, then you must demonstrate and document that process.	N/A	Required

Previous

Next

Planning your integration