Planning your marketplace integration

After you have determined your tax calculation and remittance approach with your tax advisor, continue planning your integration. The tables below provide an overview of suggested elements that marketplaces should consider implementing in their integration. These elements are not required for marketplace integrations; they are only suggestions. But be sure to consider the following benefits before moving on

These elements are designed to help ensure that tax is handled correctly and that the integration is easy to use.
These elements help you design a UI that your operations team can manage without the assistance of a developer.
If your business model shifts, and your marketplace becomes an ecommerce site, then following these guidelines makes it easier for your integration to become certified.

Advice:

Administration and utilities

This section describes the suggested elements to implement in the settings window of your integration.

Suggested element	Use Case	Endpoints
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
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
Request timeout definition	Merchants/users should define a timeout length on their backend service for API requests in AvaTax.	N/A
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

Customer record integration

This section describes the suggested elements to implement for setting up your customers.

Suggested element Use Case Endpoints

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. N/A

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

Item/charge integration

This section describes the suggested elements to implement for how you define what you're selling and how those items are associated with items in AvaTax.

Suggested element	Use Case	Endpoints
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
Item description	Merchants/users must be able to input a human-readable description for each `ItemCode` in their product catalog.	ItemModel
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
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
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
Tax code lookup	Merchants/users should be provided with a method for looking up tax codes.	ListTaxCodes

Sales/billing documentation integration

This section describes suggested elements to implement for how information is passed from an invoice or a quote.

Suggested element	Use Case	Endpoints
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
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
Document dates	Merchants/users must be able to specify the calendar date when a transaction occurs.	CreateTransactionModel
Tax calculation date	Merchants/users must be able to override the date used to calculate tax.	TaxOverrideModel
Document type	Merchants/users must be able to specify the type of document that I am creating in a transaction.	CreateTransactionModel
Header level destination address	Merchants/users must be able to specify the ship-to address for an entire transaction.	AddressModel
Header level origin address	Merchants/users must be able to specify the ship-from address for an entire transaction.	AddressModel
Line number	Merchants/users must be able to include multiple lines on a transaction, with each line specified using a unique line number.	LineItemModel
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
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
Quantity	Merchants/users must be able to specify the quantity of an item for each line of a transaction.	LineItemModel
Amount (extended)	Merchants/users must be able to specify the total amount (net currency value) for each line item in a transaction.	LineItemModel
Tax code	Merchants/users must be able to specify a tax code for each line item in a transaction.	LineItemModel
Merchant seller identifier	You may want to include a field that identifies the merchant facilitating sales on your marketplace.	LineItemModel
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
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
Determination call - Sales Order/Sales Invoice	Merchants/users must ensure that sales documents are processed through a logical document lifecycle.	N/A
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
Send discounts appropriately	Merchants/users must ensure that discounts on transactions are processed appropriately.	CreateTransactionModel LineItemModel
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
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
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
Include point of order rrigin 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
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
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
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
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
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.	CreateTransactionModel
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
Send optional header-level data elements - Purchase order number	Merchants/users should be able to specify a purchase order number for a transaction.	CreateTransactionModel
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
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
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

Previous

Next

Planning your integration