# Planning your integration Source: https://developer.avalara.com/marketplace-integration-guide/before-you-begin/planning-your-integration/ After you've 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. Keep in mind the following when completing your integration: - To help your users with tax configuration, you may want to include a link to a user guide or your Help site within your integration. - Marketplaces can save money and benefit from Streamlined Sales Tax (SST). More information about SST is available on the [Avalara web site](https://www.avalara.com/us/en/products/sales-and-use-tax/streamlined-sales-tax.html). - To track merchant transactions on your marketplace, you can leverage the `merchantSellerIdentifier` field. This field identifies the merchant facilitating sales on your marketplace. Refer to the [Multi-merchant scenario](/marketplace-integration-guide/test-transactions/multi-merchant-scenario) topic later in this document for an example. - Marketplaces should be aware of the [InitiateExportDocumentLineReport](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Reports/InitiateExportDocumentLineReport/) API. [![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Administration and utilities](javascript:void\(0\);) This section describes the settings window of your integration. Requirement Use case Endpoints/Models [Address validation service](/marketplace-integration-guide/Shared/designing/address-validation-service) 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](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Addresses/ResolveAddressPost/) or some other third-party validator [Pass integration identifier information](/marketplace-integration-guide/designing/pass-integration-identifier) Merchants/users must include information about the connection as a signature in each transaction. N/A [Option to display prices with tax included](/marketplace-integration-guide/Shared/designing/tax-included-option) Merchants/users may need to be able to show prices in transactions with the tax included. They can do this by enabling thee `taxIncluded` parameter in the line level of the `CreateTransaction` model. Note that this is required for a VAT badge. [LineItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) [![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Customer record integration](javascript:void\(0\);) This section describes the requirements for setting up your customers. Requirement Use case Endpoints/Models Type [Customer codes](/marketplace-integration-guide/Shared/designing/customer-codes) 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 Required [Entity use codes](/marketplace-integration-guide/Shared/designing/entity-use-codes) Merchants/users must be able to input a group of codes that indicate a type of exemption or exemption override. These can be standard codes and custom codes, and users can specify them at either the document or line item. It’s 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](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Definitions/ListEntityUseCodes/) [CreateTransactionModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/CreateTransactionModel/) [LineItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) Required [![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Items/charge integration](javascript:void\(0\);) This section describes the requirements for how you define what you're selling and how you associated those with an item in AvaTax. Requirement Use case Endpoints/Models [Item code](/marketplace-integration-guide/Shared/designing/item-code) Merchants/users must be able to specify a unique item code that's passed to AvaTax. Item codes allow for a maximum of 50 characters. [ItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/ItemModel/) [Item description](/marketplace-integration-guide/Shared/designing/item-description) Merchants/users must be able to input a human-readable description for each `ItemCode` in their product catalog. [ItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/ItemModel/) [AvaTax tax code mapping](/marketplace-integration-guide/Shared/designing/tax-code-mapping) Merchants/users must be able to associate an item or item category to an Avalara tax code to describe the taxability (for example, "Clothing-Shirts" – "B-to-C"). [ListTaxCodes](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Definitions/ListTaxCodes/) [Tax code lookup](/marketplace-integration-guide/Shared/designing/tax-code-lookup) Merchants/users should be provided with a method for looking up tax codes. [ListTaxCodes](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Definitions/ListTaxCodes/) [Non-standard items](/marketplace-integration-guide/Shared/designing/non-standard-items) Merchants/users must have a way of associating Freight/Shipping and/or Handling charges to an Avalara tax code to describe the taxability. [LineItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) [![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Sales/billing documentation integration](javascript:void\(0\);) This section describes requirements for how to pass information from an invoice or quote. Requirement Use case Endpoints/Models [Document code](/marketplace-integration-guide/Shared/transactions/certification-requirements/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](https://developer.avalara.com/api-reference/avatax/rest/v2/models/CreateTransactionModel/) [Customer code](/marketplace-integration-guide/Shared/transactions/certification-requirements/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](https://developer.avalara.com/api-reference/avatax/rest/v2/models/CreateTransactionModel/) [Document date](/marketplace-integration-guide/Shared/transactions/certification-requirements/document-date) Merchants/users must be able to specify the calendar date when a transaction occurs. [CreateTransactionModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/CreateTransactionModel/) [Ship-from address (header and line levels)](/marketplace-integration-guide/Shared/transactions/certification-requirements/ship-from-address) Merchants/users must be able to specify the ship-from address for an entire transaction and for a line item. [AddressModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/AddressesModel/) [Ship-to address (header and line levels)](/marketplace-integration-guide/Shared/transactions/certification-requirements/ship-to-address) Merchants/users must be able to specify the ship-to address for an entire transaction and for a line item. [AddressModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/AddressesModel/) [Line number](/marketplace-integration-guide/Shared/transactions/certification-requirements/line-number) Merchants/users must be able to include multiple lines on a transaction, with each line specified using a unique line number. [LineItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) [Item code](/marketplace-integration-guide/Shared/transactions/certification-requirements/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](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) [Item description](/marketplace-integration-guide/Shared/transactions/certification-requirements/item-description) Merchants/users must be able to include a description of an item on each line of a transaction. For [SST](https://knowledge.avalara.com/bundle/voh1659520148233_voh1659520148233/page/SST_transaction_requirements.html), this description must be human readable. [LineItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) [Quantity](/marketplace-integration-guide/Shared/transactions/certification-requirements/quantity) Merchants/users must be able to specify the quantity of an item for each line of a transaction. [LineItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) [Amount](/marketplace-integration-guide/Shared/transactions/certification-requirements/amount) Merchants/users must be able to specify the total amount for each line item in a transaction, keeping in mind the status of the `isTaxIncluded` flag. [LineItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) [Tax code](/marketplace-integration-guide/Shared/transactions/certification-requirements/tax-code) Merchants/users must be able to specify a tax code for each line item in a transaction. [LineItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) [Merchant seller identifier](/marketplace-integration-guide/designing/merchant-seller-identifier-sales) Merchants/users must be able to enter the ID of the merchant/seller on the marketplace. [LineItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) [Verify that the transaction uses the Avalara-calculated tax amount](/marketplace-integration-guide/Shared/transactions/certification-requirements/verify-avalara-calculated-tax) 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 [Shipping/freight handling](/marketplace-integration-guide/Shared/transactions/certification-requirements/shipping-freight-handling) Merchants/users must have a way to specify shipping and freight charges on a separate line in each transaction. [LineItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) [Discount transactions](/marketplace-integration-guide/Shared/transactions/certification-requirements/discount-transactions) Merchants/users must ensure that discounts on transactions are processed appropriately. [CreateTransactionModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/CreateTransactionModel/) [LineItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) [Commit transactions](/marketplace-integration-guide/Shared/transactions/certification-requirements/commit-transactions) Merchants/users must determine when to record (commit) a transaction in the AvaTax account and also ensure that invoices are reported properly. [CommitTransaction](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/CommitTransaction/) [Void/delete a document](/marketplace-integration-guide/Shared/transactions/certification-requirements/void-delete-document) If the merchant's source application supports voiding/deleting invoices, then they must allow users to void/delete invoices in AvaTax. [VoidTransactionModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/enums/VoidTransactionModel%20%3E%20code/) [Point-of-order origin address (header and line levels)](/marketplace-integration-guide/Shared/transactions/certification-requirements/poo-address) 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 or line levels. [AddressModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/AddressesModel/) [Point-of-order acceptance address (header and line levels)](/marketplace-integration-guide/Shared/transactions/certification-requirements/poa-address) 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 or line levels level. [AddressModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/AddressesModel/) [Location code](/marketplace-integration-guide/Shared/transactions/certification-requirements/location-code) If the source application supports marketplace location codes, then also include this in your integration. [AddressLocationInfo](https://developer.avalara.com/api-reference/avatax/rest/v2/models/AddressLocationInfo/) [LocationModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LocationModel/) [Reporting location code](/marketplace-integration-guide/Shared/transactions/certification-requirements/reporting-location-code) If the merchant's source application supports multiple origin addresses, then provide an option for users to specify a reporting location code in the determination request. [CreateTransactionModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/CreateTransactionModel/) [Purchase order number](/marketplace-integration-guide/Shared/transactions/certification-requirements/po-number) Merchants/users should be able to specify a purchase order number for a transaction. [CreateTransactionModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/CreateTransactionModel/) [Entity use code (header and line levels)](/marketplace-integration-guide/Shared/transactions/certification-requirements/entity-use-code) Merchants/users should be able to specify an entity/use code for each line item in a transaction. [LineItemModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/LineItemModel/) [Latitude/longitude support](/marketplace-integration-guide/Shared/transactions/certification-requirements/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](https://developer.avalara.com/api-reference/avatax/rest/v2/models/AddressesModel/) [A reasonable ratio of calculation and address validation calls to committed documents](/marketplace-integration-guide/Shared/design-the-document-workflow/reasonable-ratio-of-calls) Users must ensure that the integration minimizes traffic. AvaTax will expect to see up to approximately 10 calculations per finalized document (including for abandoned carts). Failing to do so will drive up usage and billing. You can also provide a simple "estimated tax" option, just ensure that the estimate doesn’t call to AvaTax. N/A [![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)Refunds integration](javascript:void\(0\);) Requirement Use case Endpoints/Models [Return order/return invoices workflow](/marketplace-integration-guide/Shared/transactions/certification-requirements/return-order-invoice-workflow) Merchants need to ensure that returns they commit/post documents appropriately for reporting. Ensure that this workflow matches your AvaTax sales transaction workflow. N/A [Send the original invoice date as the tax calculation date for refunds](/marketplace-integration-guide/Shared/transactions/certification-requirements/send-original-invoice-date-for-return) Merchants need to provide a method for including the original invoice date as the tax calculation date when refunding tax. [CreateTransaction](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/CreateTransaction/) [RefundTransaction](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/RefundTransaction/) [Send the current transaction date as the document date for refunds](/marketplace-integration-guide/Shared/transactions/certification-requirements/send-current-transaction-date) Merchants must allow users to specify the current date as the transaction date for the refund. [CreateTransaction](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/CreateTransaction/) [RefundTransaction](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/RefundTransaction/) [Send a negative line item amount with a positive quantity](/marketplace-integration-guide/Shared/transactions/certification-requirements/send-negative-amount-with-positive-quantity) `ReturnInvoice` transactions must specify a negative amount value and a positive quantity. [CreateTransaction](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/CreateTransaction/) [Support tax-only adjustments](/marketplace-integration-guide/Shared/transactions/certification-requirements/support-tax-only-adjustments) If your platform allows refunds for calculated tax, then you should include this in your AvaTax implementation. [RefundTransaction](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/RefundTransaction/) [Support tax amount tax overrides](/marketplace-integration-guide/Shared/transactions/certification-requirements/support-tax-amount-tax-overrides) Merchants should allow users to override the tax amount in a transaction. [CreateTransaction](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/CreateTransaction/) [![Closed](https://avalara-devdocs-prod.mcoutput.com/avatax-for-marketplaces/Content/Skins/Default/Stylesheets/Images/transparent.gif)POS integration](javascript:void\(0\);) Requirement Use case Endpoints/Models [Use the correct address type for your POS](/marketplace-integration-guide/Shared/transactions/certification-requirements/use-the-correct-address-type-for-your-pos) For cash-and-carry sales, ensure that the transaction either uses a single location address or that the transaction has the same ship-to and ship-from address. [AddressesModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/AddressesModel/) [Reporting location code](/marketplace-integration-guide/Shared/transactions/certification-requirements/reporting-location-code) Provide an option for users to specify a reporting location code in the determination request. This code represents the location/store identifier from the source system being sent in the request. [CreateTransactionModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/CreateTransactionModel/)