Tax API

The tax API is used to calculate and display tax amounts to the consumer on an order before the order is placed. Tax computations are made on the item prices only, but a quote request can obtain the estimate for one or more items.

For detailed information on the tax API, see the documentation in the Payments & Fraud section of the Integration Center.

Tax URI Summary

The tax URI uses the service identifier taxes.

Operation	Action	URI Template	URI Example	Transaction Type	Unique RequestID Needed for Duplicate Detection?	Non-URI Request Payload	Response
quote	POST	/vM.m/stores/storeId/taxes/quote.format	/v1.0/stores/ABCD/taxes/quote	Create a tax quote as specified by input XML	No	XML	XML
invoice	POST	/vM.m/stores/storeId/taxes/invoice.format	/v1.0/stores/ABCD/taxes/invoice	Create a tax invoice as specified by input XML. Asynchronous request. An AckReply is sent from public-api to external client request.	No	XML	XML
distribute	POST	/vM.m/stores/storeId/taxes/distribute.format	/v1.0/stores/ABCD/taxes/distribute	Create a tax distribute as specified by input XML. Asynchronous request. An AckReply is sent from public-api to external client request.	No	XML	XML

Tax Data Guidelines

The tax API requires an address to properly assess charges. In nearly all cases, the shipping address is used to determine taxes. However, there are certain cases when shipping address is not available, such as the purchase of a online gift certificate or an eBook. In cases where a shipping address is not available, the billing address should be used instead. For this reason, billing address is required.

When submitting a tax quote request to the tax API for the calculation of total order tax, the CalculatedTax element at TaxDutyFeeQuoteResponse/Destinations/Destination/Items/OrderItem/Pricing/Merchandise/TaxData/Taxes/Tax/CalculatedTax will have the tax for merchandise price. The system provides the tax for each price group associated with the item such as merchandise, shipping, and duty. The total of tax and duty for all price groups of the item will have to be calculated by the client for display and proper submission to payment authorization and order services. This would be the summation of the CalculatedTax element under each price group of the item plus the duty amount under the Duty group.

Taxes on discounts, though they may be submitted as separate charges in the create order message, are summed together by the tax service and submitted for tax calculation as a single net price (inclusive of all discounting). There is not a need to include the discounts separately within the allocated fields, other than reporting purposes.

For successful processing of TaxDutyQuoteRequest messages, prevent the literal string null from being sent in place of missing data. The null strings might pass XSD validation with null strings, but they cause a variety of failures in downstream systems.