ApiKey: <your API key>Content-Type: text/xml
Radial Integration | 2016
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.
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.
<?xml version="1.0" encoding="UTF-8"?>
<TaxDutyQuoteRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<Currency>USD</Currency> (1)
<BillingInformation ref="bill_dest1"/> (2)
<Shipping>
<ShipGroups> (3)
<ShipGroup id="shipgroup_1">
<DestinationTarget ref="dest1"/> (4)
<Items>
<OrderItem lineNumber="1"> (5)
<ItemId>12-34567890</ItemId> (6)
<ItemDesc>The Coolest Thing</ItemDesc> <Origins> <AdminOrigin> (7)
<Line1>1350 Broadway, Third Floor</Line1> <City>New York</City> <MainDivision>NY</MainDivision> <CountryCode>US</CountryCode> <PostalCode>10018</PostalCode> </AdminOrigin> <ShippingOrigin> (8)
<Line1>7601 Trade Port Drive</Line1> <City>Shepherdsville</City> <MainDivision>KY</MainDivision> <CountryCode>US</CountryCode> <PostalCode>40165</PostalCode> </ShippingOrigin> </Origins> <Quantity>1</Quantity> (9)
<Pricing> (10)
<Merchandise>
<Amount>29.95</Amount> (11)
<TaxClass>76800</TaxClass> (12)
<PromotionalDiscounts> (13)
<Discount calculateDuty="false" id="334"> <Amount>10.00</Amount> </Discount> </PromotionalDiscounts> <UnitPrice>39.95</UnitPrice> (14)
</Merchandise>
<Shipping>
<Amount>8.95</Amount>
</Shipping>
</Pricing>
</OrderItem>
</Items>
</ShipGroup>
</ShipGroups>
<Destinations>
<MailingAddress id="dest1"> (4)
<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"> (2)
<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>| 1 | The currency of the transaction for this order |
| 2 | Billing address provided by the customer |
| 3 | 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 |
| 4 | The validated ship to address provided by the customer |
| 5 | Each //OrderItem represents an order line and is uniquely identified by
by the application provided //OrderItem/@lineNumber value. |
| 6 | The Radial item identifier for the product on this line |
| 7 | Ship from address provided by an inventory details API call for this line, or a default configured in your application |
| 8 | The administrative address for the organization running your application |
| 9 | The quantity requested for this line |
| 10 | Pricing info for this line |
| 11 | Net price on the line (unit price - discounts) |
| 12 | 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. |
| 13 | Discounts on the line |
| 14 | Unit price on the line |
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:
| 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.
<?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> (1)
<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> (1)
<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> (1)
<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>| 1 | Tax details added to the request by the API for item pricing, discounts and shipping. |
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"> (1)
<CreateTimestamp>2016-02-19T14:44:45+00:00</CreateTimestamp> (2)
<Code>InvalidRequestXmlException</Code> (3)
<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> (4)
</Fault>| 1 | Message payload describing an API error (http status 400 or 500) |
| 2 | Timestamp describing when the error occurred on the server |
| 3 | Unique code describing the error |
| 4 | Description of the error |
Copyright © 2017 Radial. All rights reserved.