How to Build a Tax Quote Request
How to Build a Tax Quote API Request
A tax quote can be obtained for an order by using the ROM Tax Quote API. The API will calculate any applicable duties, sales and/or use tax for each line.
Building a Tax Quote Request
A tax quote API request message requires, for each line item:
-
The Radial-supplied item identifier
-
A unique line identifier that your application provides
-
A ship to address collected from the customer
-
A ship from address provided by a previous call from the ROM Inventory Details API; also see InventoryDetailResponseMessage → TaxDutyQuoteRequest
-
An administrative address provided by your application
-
Tax class
-
Pricing
The figure below shows an example tax quote API request for a simple one-line order shipped within the United States. The annotations identify and describe input data to the request.
Example Tax Quote API Request: One Line
<?xml version="1.0" encoding="UTF-8"?>
<TaxDutyQuoteRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<Currency>USD</Currency> <!-- see NOTE1 -->
<BillingInformation ref="bill_dest1"/> <!-- see NOTE2 -->
<Shipping>
<ShipGroups> <!-- see NOTE3 -->
<ShipGroup id="shipgroup_1">
<DestinationTarget ref="dest1"/> <!-- see NOTE4 -->
<Items>
<OrderItem lineNumber="1"> <!-- see NOTE5 -->
<ItemId>12-34567890</ItemId> <!-- see NOTE6 -->
<ItemDesc>The Coolest Thing</ItemDesc>
<Origins>
<AdminOrigin> <!-- see NOTE7 -->
<Line1>1350 Broadway, Third Floor</Line1>
<City>New York</City>
<MainDivision>NY</MainDivision>
<CountryCode>US</CountryCode>
<PostalCode>10018</PostalCode>
</AdminOrigin>
<ShippingOrigin> <!-- see NOTE8 -->
<Line1>7601 Trade Port Drive</Line1>
<City>Shepherdsville</City>
<MainDivision>KY</MainDivision>
<CountryCode>US</CountryCode>
<PostalCode>40165</PostalCode>
</ShippingOrigin>
</Origins>
<Quantity>1</Quantity> <!-- see NOTE9 -->
<Pricing> <!-- see NOTE10 -->
<Merchandise>
<Amount>29.95</Amount> <!-- see NOTE11 -->
<TaxClass>76800</TaxClass> <!-- see NOTE12 -->
<PromotionalDiscounts> <!-- see NOTE13 -->
<Discount calculateDuty="false" id="334">
<Amount>10.00</Amount>
</Discount>
</PromotionalDiscounts>
<UnitPrice>39.95</UnitPrice> <!-- see NOTE14 -->
</Merchandise>
<Shipping>
<Amount>8.95</Amount>
<TaxClass>93000</TaxClass>
</Shipping>
</Pricing>
</OrderItem>
</Items>
</ShipGroup>
</ShipGroups>
<Destinations>
<MailingAddress id="dest1"> <!-- see NOTE4 -->
<PersonName>
<LastName>Shopper</LastName>
<FirstName>Joe</FirstName>
</PersonName>
<Address>
<Line1>630 Allendale Rd</Line1>
<City>King of Prussia</City>
<MainDivision>PA</MainDivision>
<CountryCode>US</CountryCode>
<PostalCode>19406</PostalCode>
</Address>
</MailingAddress>
<MailingAddress id="bill_dest1"> <!-- see NOTE2 -->
<PersonName>
<LastName>Shopper</LastName>
<FirstName>Joe</FirstName>
</PersonName>
<Address>
<Line1>630 Allendale Road</Line1>
<City>King Of Prussia</City>
<MainDivision>PA</MainDivision>
<CountryCode>US</CountryCode>
<PostalCode>19406</PostalCode>
</Address>
</MailingAddress>
</Destinations>
</Shipping>
</TaxDutyQuoteRequest>| NOTE1 | The currency of the transaction for this order |
| NOTE2 | Billing address provided by the customer |
| NOTE3 | A ship group is a set of one or more order lines which share a common
ship to address identified in the //ShipGroup/DestinationTarget
reference |
| NOTE4 | The validated ship to address provided by the customer |
| NOTE5 | Each //OrderItem represents an order line and is uniquely identified by
by the application provided //OrderItem/@lineNumber value. |
| NOTE6 | The Radial item identifier for the product on this line |
| NOTE7 | Ship from address provided by an inventory details API call for this line, or a default configured in your application |
| NOTE8 | The administrative address for the organization running your application |
| NOTE9 | The quantity requested for this line |
| NOTE10 | Pricing info for this line |
| NOTE11 | Net price on the line (unit price - discounts) |
| NOTE12 | The tax class for the item on this line.
This value corresponds to the
//Item/BaseAttributes/TaxCode value provided for the item in the
item master file. |
| NOTE13 | Discounts on the line |
| NOTE14 | Unit price on the line |
Interpreting the ROM Tax Quote API Response
The request is made by HTTPS POST to
/v1.0/stores/<your Store ID>/inventory/quantity/get.xml
and must include the following headers:
ApiKey: <your API key>Content-Type: text/xml
The ROM tax quote API supports the following HTTP response status codes:
Example Tax Quote API Response: One Line
| Status | Description | Action |
|---|---|---|
|
200 |
Success |
Interrogate the response payload for additional information. |
|
400 |
Bad request. The API could not process the request due to either a syntax error or bad data in the provided request payload. |
This is a programming time error. Interrogate the fault message in the response payload for more information. Fix the syntax or data issue in the requesting application. |
|
500 |
API processing error. The API could not process the request due to a temporary internal error. |
The application should continue processing the order. When the order is submitted via the ROM Create Order API the following should be set on the order message: /OrderCreateRequest/Order/TaxHeader/Error = true This will tell the ROM order management component to retry the tax quote after order submission. |
|
Timeouts
e-commerce application should set a reasonable timeout on all ROM API calls.
If an API call does not respond within the configured timeout the
application should proceed as if the call returned a 500 http status.
|
The tax quote API response payload is an XML message providing tax details for each line on the order. The figure below shows a response message corresponding the the one-line example request above. The response message contains the same information provided by applcation in the request message with tax details added by the API to the item price, discounts and shipping. Tax data include the tax type, jurisdiction, effective tax rate, taxable amount and calculated tax.
Example Tax Quote API Response: One Line
<?xml version="1.0" encoding="UTF-8"?>
<TaxDutyQuoteResponse xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<Shipping>
<ShipGroups>
<ShipGroup id="shipgroup_1"
taxDutyDisplayPrefCode="CONSOLIDATED_TAXES_ONLY">
<DestinationTarget ref="dest1"/>
<Items>
<OrderItem lineNumber="1">
<ItemId>12-34567890</ItemId>
<ItemDesc>The Coolest Thing</ItemDesc>
<HTSCode/>
<Quantity>1</Quantity>
<Pricing>
<Merchandise>
<Amount>29.95</Amount>
<TaxData>
<TaxClass>76800</TaxClass>
<Taxes> <!-- see NOTE1 -->
<Tax taxType="SELLER_USE" taxability="TAXABLE">
<Situs>DESTINATION</Situs>
<Jurisdiction jurisdictionLevel="STATE"
jurisdictionId="31152">PENNSYLVANIA</Jurisdiction>
<Imposition impositionType="General Sales and Use Tax">
Sales and Use Tax</Imposition>
<EffectiveRate>0.06</EffectiveRate>
<TaxableAmount>19.95</TaxableAmount>
<CalculatedTax>1.2</CalculatedTax>
</Tax>
</Taxes>
</TaxData>
<PromotionalDiscounts>
<Discount id="334" calculateDuty="false">
<Amount>10.00</Amount>
<Taxes> <!-- see NOTE1 -->
<Tax taxType="SELLER_USE" taxability="TAXABLE">
<Situs>DESTINATION</Situs>
<Jurisdiction jurisdictionLevel="STATE"
jurisdictionId="31152">PENNSYLVANIA</Jurisdiction>
<Imposition impositionType="General Sales and Use Tax">
Sales and Use Tax</Imposition>
<EffectiveRate>0.0</EffectiveRate>
<TaxableAmount>0.0</TaxableAmount>
<CalculatedTax>0.0</CalculatedTax>
</Tax>
</Taxes>
</Discount>
</PromotionalDiscounts>
<UnitPrice>39.95</UnitPrice>
</Merchandise>
<Shipping>
<Amount>8.95</Amount>
<TaxData>
<Taxes> <!-- see NOTE1 -->
<Tax taxType="SELLER_USE" taxability="TAXABLE">
<Situs>DESTINATION</Situs>
<Jurisdiction jurisdictionLevel="STATE"
jurisdictionId="31152">PENNSYLVANIA</Jurisdiction>
<Imposition impositionType="General Sales and Use Tax">
Sales and Use Tax</Imposition>
<EffectiveRate>0.06</EffectiveRate>
<TaxableAmount>8.95</TaxableAmount>
<CalculatedTax>0.54</CalculatedTax>
</Tax>
</Taxes>
</TaxData>
</Shipping>
</Pricing>
</OrderItem>
</Items>
</ShipGroup>
</ShipGroups>
<Destinations>
<MailingAddress id="dest1">
<PersonName>
<LastName>Shopper</LastName>
<FirstName>Joe</FirstName>
</PersonName>
<Address>
<Line1>630 Allendale Rd</Line1>
<City>King of Prussia</City>
<MainDivision>PA</MainDivision>
<CountryCode>US</CountryCode>
<PostalCode>19406</PostalCode>
</Address>
</MailingAddress>
<MailingAddress id="bill_dest1">
<PersonName>
<LastName>Shopper</LastName>
<FirstName>Joe</FirstName>
</PersonName>
<Address>
<Line1>630 Allendale Road</Line1>
<City>King Of Prussia</City>
<MainDivision>PA</MainDivision>
<CountryCode>US</CountryCode>
<PostalCode>19406</PostalCode>
</Address>
</MailingAddress>
</Destinations>
</Shipping>
</TaxDutyQuoteResponse>| NOTE1 | Tax details added to the request by the API for item pricing, discounts and shipping. |
Interpreting a Fault Response
Example fault XML for an request message parsing error (HTTP status 400). In this example an item description is longer than the maximum length that the message field can accommodate.
<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0"> <!-- see NOTE1 -->
<CreateTimestamp>2016-02-19T14:44:45+00:00</CreateTimestamp> <!-- see NOTE2 -->
<Code>InvalidRequestXmlException</Code> <!-- see NOTE3 -->
<Description>cvc-maxLength-valid: Value 'The Coolest Thing Online'
with length = '24' is not facet-valid with respect to maxLength '20'
for type 'ItemDescription'.</Description> <!-- see NOTE4 -->
</Fault>| NOTE1 | Message payload describing an API error (http status 400 or 500) |
| NOTE2 | Timestamp describing when the error occurred on the server |
| NOTE3 | Unique code describing the error |
| NOTE4 | Description of the error |