TDF Tax Quote

Overview

The webstore calls the TDF Tax Quote operation to perform the following tax quote processing:

  • Calculate and return the tax quote for every line item.
  • Calculate the duties and applicable taxes for international shipments, based on the inputs and configuration.
  • Calculate tax for duty, for any line items that have duty.
  • Calculate any legal fees and applicable taxes.
  • Calculate tax for fees, for any line items that have fees.

This synchronous operation creates a quote request (TaxDutyQuoteRequest) on the Tax Service and returns either a valid response (TaxDutyQuoteResponse) or a fault with details.

URI Summary

Action URI Template URI Example Non-URI Request Response
POST /v[M.m]/stores/[StoreId]/taxes/quote.[format] /v1.0/stores/AStoreId/taxes/quote.xml XML 200 + XML response

Schemas

Request Examples

Click each heading below to see the example message.

<TaxDutyQuoteRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://api.gsicommerce.com/schema/checkout/1.0 
   TaxDutyFee-QuoteRequest-1.0.xsd">
   <Currency>USD</Currency>
   <VATInclusivePricing>false</VATInclusivePricing>
   <CustomerTaxId>string</CustomerTaxId>
   <BillingInformation ref="bill_dest1"/>
   <Shipping>
      <ShipGroups>
         <ShipGroup id="shipgroup_1">
            <DestinationTarget ref="dest1"/>
            <Items>
               <OrderItem lineNumber="1">
                  <ItemId>1</ItemId>
                  <ItemDesc>shirt</ItemDesc>
                  <HTSCode>newCode</HTSCode>
                  <Origins>
                     <AdminOrigin>
                        <Line1>401 Allendale Rd</Line1>
                        <Line2>Building 1</Line2>
                        <Line3>Floor 2</Line3>
                        <Line4>Appartment 3</Line4>
                        <City>King of Prussia</City>
                        <MainDivision>PA</MainDivision>
                        <CountryCode>USA</CountryCode>
                        <PostalCode>19460</PostalCode>
                     </AdminOrigin>
                     <ShippingOrigin>
                        <Line1>401 Allendale Rd</Line1>
                        <Line2>Building 1</Line2>
                        <Line3>Floor 2</Line3>
                        <Line4>Appartment 3</Line4>
                        <City>King of Prussia</City>
                        <MainDivision>PA</MainDivision>
                        <CountryCode>USA</CountryCode>
                        <PostalCode>19460</PostalCode>
                     </ShippingOrigin>
                     <ManufacturingCountryCode>US</ManufacturingCountryCode>
                  </Origins>
                  <Quantity>3</Quantity>
                  <Pricing>
                     <Merchandise>
                        <Amount>1000.00</Amount>
                        <TaxClass>93000</TaxClass>
                        <PromotionalDiscounts>
                           <Discount id="id1" calculateDuty="true">
                              <Amount>100.00</Amount>
                           </Discount>
                        </PromotionalDiscounts>
                        <UnitPrice>100.00</UnitPrice>
                     </Merchandise>
                     <Shipping>
                        <Amount>100.00</Amount>
                        <TaxClass>93000</TaxClass>
                        <PromotionalDiscounts>
                           <Discount id="id2" calculateDuty="true">
                              <Amount>10.00</Amount>
                           </Discount>
                        </PromotionalDiscounts>
                     </Shipping>
                     <Duty>
                        <Amount>100.00</Amount>
                        <PromotionalDiscounts>
                           <Discount id="id3" calculateDuty="true">
                              <Amount>10.00</Amount>
                           </Discount>
                        </PromotionalDiscounts>
                        <CalculationError>string</CalculationError>
                     </Duty>
                  </Pricing>
                  <Gifting id="giftingId">
                     <ItemId>itemId</ItemId>
                     <ItemDesc>itemDesc</ItemDesc>
                     <Pricing>
                        <Amount>1000.00</Amount>
                        <TaxClass>93000</TaxClass>
                        <PromotionalDiscounts>
                           <Discount id="discountId" calculateDuty="true">
                              <Amount>100.00</Amount>
                           </Discount>
                        </PromotionalDiscounts>
                        <UnitPrice>1000.00</UnitPrice>
                     </Pricing>
                  </Gifting>
                  <Customization>
                     <CustomFeatureList>
                        <CustomFeature id="color-blue">
                           <CustomizationId>1234</CustomizationId>
                           <ItemId>blueId</ItemId>
                           <ItemDesc>Color Blue</ItemDesc>
                           <Upcharge>
                              <Amount>100.00</Amount>
                              <TaxClass>93000</TaxClass>
                              <PromotionalDiscounts>
                                 <Discount id="discountid" calculateDuty="true">
                                    <Amount>10.00</Amount>
                                 </Discount>
                              </PromotionalDiscounts>
                              <UnitPrice>100.00</UnitPrice>
                           </Upcharge>
                        </CustomFeature>
                     </CustomFeatureList>
                     <BasePrice>
                        <Amount>100.00</Amount>
                        <TaxClass>93000</TaxClass>
                        <PromotionalDiscounts>
                           <Discount id="discountId" calculateDuty="false">
                              <Amount>10.00</Amount>
                           </Discount>
                        </PromotionalDiscounts>
                        <UnitPrice>1000.00</UnitPrice>
                     </BasePrice>
                  </Customization>
               </OrderItem>
            </Items>
            <Gifting id="giftingId">
               <ItemId>itemId</ItemId>
               <ItemDesc>itemDesc</ItemDesc>
               <Pricing>
                  <Amount>1000.00</Amount>
                  <TaxClass>9300</TaxClass>
                  <PromotionalDiscounts>
                     <Discount id="discountId" calculateDuty="false">
                        <Amount>100.00</Amount>
                     </Discount>
                  </PromotionalDiscounts>
                  <UnitPrice>1000.00</UnitPrice>
               </Pricing>
            </Gifting>
         </ShipGroup>
      </ShipGroups>
      <Destinations>
         <MailingAddress id="bill_dest1">
            <PersonName>
               <LastName>John</LastName>
               <FirstName>Smith</FirstName>
            </PersonName>
            <Address>
               <Line1>401 Allendale Rd</Line1>
               <Line2>Building 1</Line2>
               <Line3>Floor 2</Line3>
               <Line4>Appartment 3</Line4>
               <City>King of Prussia</City>
               <MainDivision>PA</MainDivision>
               <CountryCode>USA</CountryCode>
               <PostalCode>19460</PostalCode>
            </Address>
         </MailingAddress>
         <MailingAddress id="dest1">
            <PersonName>
               <LastName>John</LastName>
               <FirstName>Smith</FirstName>
            </PersonName>
            <Address>
               <Line1>401 Allendale Rd</Line1>
               <Line2>Building 1</Line2>
               <Line3>Floor 2</Line3>
               <Line4>Appartment 3</Line4>
               <City>King of Prussia</City>
               <MainDivision>PA</MainDivision>
               <CountryCode>USA</CountryCode>
               <PostalCode>19460</PostalCode>                
            </Address>
         </MailingAddress>
      </Destinations>
   </Shipping>
</TaxDutyQuoteRequest>

Note: VatInclusivePricing element can be set to true or false for quotations depending on whether the item amount sent in the Tax Quotation already includes VAT or not.

<?xml version="1.0" encoding="UTF-8"?>
<TaxDutyQuoteRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xsi:schemaLocation="http://api.gsicommerce.com/schema/checkout/1.0 TaxDutyFee-QuoteRequest-1.0.xsd">
  <Currency>USD</Currency>
  <VATInclusivePricing>true</VATInclusivePricing>
  <BillingInformation ref="bill_dest_1"/>
  <Shipping>
    <ShipGroups>
      <ShipGroup chargeType="FLATRATE" id="shipgroup_1">
        <DestinationTarget ref="dest_1"/>
        <Items>
          <OrderItem lineNumber="1">
            <ItemId>123</ItemId>
            <ItemDesc>Black Tennis Shoes</ItemDesc>  
            <Origins>
              <AdminOrigin>
                <Line1>114-115 St James's St</Line1>
                <City>Brighton</City>
                <CountryCode>UK</CountryCode>
                <PostalCode>BN2 1TH</PostalCode>
              </AdminOrigin>
              <ShippingOrigin>
                <Line1>114-115 St James's St</Line1>
                <City>Brighton</City>
                <CountryCode>UK</CountryCode>
                <PostalCode>BN2 1TH</PostalCode>
              </ShippingOrigin>
              <ManufacturingCountryCode>US</ManufacturingCountryCode>
            </Origins>
            <Quantity>2</Quantity>
            <Pricing>
              <Merchandise>
                <Amount>100.00</Amount>
                <TaxClass>76800</TaxClass>
                <PromotionalDiscounts>
                   <Discount id="id1">
                    <Amount>10.00</Amount>
                   </Discount>
                </PromotionalDiscounts>
                <UnitPrice>100.00</UnitPrice>
              </Merchandise>
              <Shipping>
                <Amount>20.00</Amount>
                <TaxClass>93000</TaxClass>
                <PromotionalDiscounts>
                   <Discount id="id2">
                    <Amount>10.00</Amount>
                   </Discount>
                </PromotionalDiscounts>
              </Shipping>
            </Pricing>
          </OrderItem>
        </Items>
      </ShipGroup>
    </ShipGroups>
    <Destinations>
      <MailingAddress id="dest_1">
        <PersonName>
          <LastName>firstName</LastName>
          <FirstName>lastName</FirstName>
        </PersonName>
        <Address>
          <Line1>114-115 St James's St</Line1>
          <City>Brighton</City>
          <CountryCode>UK</CountryCode>
          <PostalCode>BN2 1TH</PostalCode>
        </Address>
      </MailingAddress>
      <MailingAddress id="bill_dest_1">
        <PersonName>
          <LastName>firstName</LastName>
          <FirstName>lastName</FirstName>
        </PersonName>
        <Address>
          <Line1>114-115 St James's St</Line1>
          <City>Brighton</City>
          <CountryCode>UK</CountryCode>
          <PostalCode>BN2 1TH</PostalCode>
        </Address>
      </MailingAddress>
    </Destinations>
  </Shipping>
</TaxDutyQuoteRequest>

Response Examples

Click each heading below to see the example message.

<TaxDutyQuoteResponse xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://api.gsicommerce.com/schema/checkout/1.0 
   TaxDutyFee-QuoteResponse-1.0.xsd">
   <Shipping>
      <ShipGroups>
         <ShipGroup id="ship_group1">
            <DestinationTarget ref="dest1"/>
            <Items>
               <OrderItem lineNumber="1">
                  <ItemId>123</ItemId>
                  <ItemDesc>Black Tennis Shoes</ItemDesc>
                  <HTSCode>duty code</HTSCode>
                  <Quantity>2</Quantity>
                  <Pricing>
                     <Merchandise>
                        <Amount>1000.00</Amount>
                        <TaxData>
                           <TaxClass>9300</TaxClass>
                           <Taxes>
                              <Tax taxType="SALES" taxability="TAXABLE">
                                 <Situs>DESTINATION</Situs>
                                 <Jurisdiction jurisdictionLevel="STATE" 
                                 jurisdictionId="PA">Pennsylvania</Jurisdiction>
                                 <Imposition impositionType="imp">imposition</Imposition>
                                 <EffectiveRate>0.06</EffectiveRate>
                                 <TaxableAmount>1000.00</TaxableAmount>
                                 <CalculatedTax>60.00</CalculatedTax>
                                 <SellerRegistrationId>123</SellerRegistrationId>
                              </Tax>
                           </Taxes>
                        </TaxData>
                        <PromotionalDiscounts>
                           <Discount id="334" calculateDuty="false">
                              <Amount>20.00</Amount>
                              <Taxes>
                                 <Tax taxType="SALES" taxability="TAXABLE">
                                    <Situs>DESTINATION</Situs>
                                    <Jurisdiction jurisdictionLevel="STATE" 
                                    jurisdictionId="PA">Pennsylvania</Jurisdiction>
                                    <Imposition impositionType="imp">imposition</Imposition>
                                    <EffectiveRate>0.06</EffectiveRate>
                                    <TaxableAmount>20.00</TaxableAmount>
                                    <CalculatedTax>1.20</CalculatedTax>
                                    <SellerRegistrationId>123</SellerRegistrationId>
                                 </Tax>
                              </Taxes>
                           </Discount>
                        </PromotionalDiscounts>
                        <UnitPrice>500.00</UnitPrice>
                     </Merchandise>
                     <Shipping>
                        <Amount>20.00</Amount>
                        <TaxData>
                           <TaxClass>93000</TaxClass>
                           <Taxes>
                              <Tax taxType="SALES" taxability="TAXABLE">
                                 <Situs>DESTINATION</Situs>
                                 <Jurisdiction jurisdictionLevel="STATE" 
                                 jurisdictionId="PA">Pennsylvania</Jurisdiction>
                                 <Imposition impositionType="imp">imposition</Imposition>
                                 <EffectiveRate>0.06</EffectiveRate>
                                 <TaxableAmount>20.00</TaxableAmount>
                                 <CalculatedTax>1.20</CalculatedTax>
                                 <SellerRegistrationId>123</SellerRegistrationId>
                              </Tax>
                           </Taxes>
                        </TaxData>
                     </Shipping>
                     <Duty>
                        <Amount>4.00</Amount>
                        <TaxData>
                           <TaxClass>34343</TaxClass>
                           <Taxes>
                              <Tax taxType="IMPORT_VAT" taxability="TAXABLE">
                                 <Situs>DESTINATION</Situs>
                                 <Jurisdiction jurisdictionLevel="STATE" 
                                 jurisdictionId="PA">Pennsylvania</Jurisdiction>
                                 <Imposition impositionType="imp">imposition</Imposition>
                                 <EffectiveRate>0.04</EffectiveRate>
                                 <TaxableAmount>4.00</TaxableAmount>
                                 <CalculatedTax>0.16</CalculatedTax>
                                 <SellerRegistrationId>123</SellerRegistrationId>
                              </Tax>
                           </Taxes>
                        </TaxData>
                     </Duty>
                  </Pricing>
               </OrderItem>
            </Items>
            <Gifting id="giftingId">
               <ItemId>itemId</ItemId>
               <ItemDesc>itemDesc</ItemDesc>
               <Pricing>
                  <Amount>1000.00</Amount>
                  <TaxClass>9300</TaxClass>
                  <PromotionalDiscounts>
                     <Discount id="discountId" calculateDuty="false">
                        <Amount>100.00</Amount>
                     </Discount>
                  </PromotionalDiscounts>
                  <UnitPrice>1000.00</UnitPrice>
               </Pricing>
            </Gifting>
         </ShipGroup>
      </ShipGroups>
      <Destinations>
         <MailingAddress id="dest1">
            <PersonName>
               <LastName>John</LastName>
               <FirstName>Smith</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>
   <TaxTransactionId>3721007</TaxTransactionId>
</TaxDutyQuoteResponse>


<?xml version="1.0" encoding="UTF-8"?>
<TaxDutyQuoteResponse xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <Shipping>
      <ShipGroups>
         <ShipGroup id="shipgroup_1" chargeType="FLATRATE">
            <DestinationTarget ref="dest_1"/>
            <Items>
               <OrderItem lineNumber="1">
                  <ItemId>123</ItemId>
                  <ItemDesc>Black Tennis Shoes</ItemDesc>
                  <HTSCode/>
                  <Quantity>2</Quantity>
                  <Pricing>
                     <Merchandise>
                        <Amount>100.00</Amount>
                        <TaxData>
                           <TaxClass>76800</TaxClass>
                           <Taxes>
                              <Tax taxType="VAT" taxability="TAXABLE">
                                 <Situs>DESTINATION</Situs>
                                 <Jurisdiction jurisdictionLevel="COUNTRY" jurisdictionId="78295">UNITED KINGDOM</Jurisdiction>
                                 <Imposition impositionType="VAT">VAT</Imposition>
                                 <EffectiveRate>0.2</EffectiveRate>
                                 <TaxableAmount>75.0</TaxableAmount>
                                 <CalculatedTax>15.0</CalculatedTax>
                                 <SellerRegistrationId>123</SellerRegistrationId>
                                 <InvoiceTextCodes>
                                    <InvoiceTextCode>21</InvoiceTextCode>
                                 </InvoiceTextCodes>
                              </Tax>
                           </Taxes>
                        </TaxData>
                        <PromotionalDiscounts>
                           <Discount id="id1">
                              <Amount>10.00</Amount>
                              <Taxes>
                                 <Tax taxType="VAT" taxability="TAXABLE">
                                    <Situs>DESTINATION</Situs>
                                    <Jurisdiction jurisdictionLevel="COUNTRY" jurisdictionId="78295">UNITED KINGDOM</Jurisdiction>
                                    <Imposition impositionType="VAT">VAT</Imposition>
                                    <EffectiveRate>0.0</EffectiveRate>
                                    <TaxableAmount>0.0</TaxableAmount>
                                    <CalculatedTax>0.0</CalculatedTax>
                                    <SellerRegistrationId>123</SellerRegistrationId>
                                    <InvoiceTextCodes>
                                       <InvoiceTextCode>21</InvoiceTextCode>
                                    </InvoiceTextCodes>
                                 </Tax>
                              </Taxes>
                           </Discount>
                        </PromotionalDiscounts>      
                        <UnitPrice>100.00</UnitPrice>
                     </Merchandise>
                     <Shipping>
                        <Amount>20.00</Amount>
                        <TaxData>
                           <Taxes>
                              <TaxClass>93000</TaxClass>
                              <Tax taxType="VAT" taxability="TAXABLE">
                                 <Situs>DESTINATION</Situs>
                                 <Jurisdiction jurisdictionLevel="COUNTRY" jurisdictionId="78295">UNITED KINGDOM</Jurisdiction>
                                 <Imposition impositionType="VAT">VAT</Imposition>
                                 <EffectiveRate>0.2</EffectiveRate>
                                 <TaxableAmount>8.33</TaxableAmount>
                                 <CalculatedTax>1.67</CalculatedTax>
                                 <SellerRegistrationId>123</SellerRegistrationId>
                                 <InvoiceTextCodes>
                                    <InvoiceTextCode>21</InvoiceTextCode>
                                 </InvoiceTextCodes>
                              </Tax>
                           </Taxes>
                        </TaxData>
                        <PromotionalDiscounts>
                           <Discount id="id2">
                              <Amount>10.00</Amount>
                              <Taxes>
                                 <Tax taxType="VAT" taxability="TAXABLE">
                                    <Situs>DESTINATION</Situs>
                                    <Jurisdiction jurisdictionLevel="COUNTRY" jurisdictionId="78295">UNITED KINGDOM</Jurisdiction>
                                    <Imposition impositionType="VAT">VAT</Imposition>
                                    <EffectiveRate>0.0</EffectiveRate>
                                    <TaxableAmount>0.0</TaxableAmount>
                                    <CalculatedTax>0.0</CalculatedTax>
                                    <SellerRegistrationId>123</SellerRegistrationId>
                                    <InvoiceTextCodes>
                                       <InvoiceTextCode>21</InvoiceTextCode>
                                    </InvoiceTextCodes>
                                 </Tax>
                              </Taxes>
                           </Discount>
                        </PromotionalDiscounts>
                     </Shipping>
                  </Pricing>
               </OrderItem>
            </Items>
         </ShipGroup>
      </ShipGroups>
      <Destinations>
         <MailingAddress id="dest_1">
            <PersonName>
               <LastName>firstName</LastName>
               <FirstName>lastName</FirstName>
            </PersonName>
            <Address>
               <Line1>114-115 St James's St</Line1>
               <City>Brighton</City>
               <CountryCode>UK</CountryCode>
               <PostalCode>BN2 1TH</PostalCode>
            </Address>
         </MailingAddress>
         <MailingAddress id="bill_dest_1">
            <PersonName>
               <LastName>firstName</LastName>
               <FirstName>lastName</FirstName>
            </PersonName>
            <Address>
               <Line1>114-115 St James's St</Line1>
               <City>Brighton</City>
               <CountryCode>UK</CountryCode>
               <PostalCode>BN2 1TH</PostalCode>
            </Address>
         </MailingAddress>
      </Destinations>
    </Shipping>
   <TaxTransactionId>931183</TaxTransactionId>
</TaxDutyQuoteResponse>

Request and Response Data Elements

Element Request Response Description Type Restriction
StoreId Required NA Store ID used in the URL String Max 20 characters
Currency Required NA Type of currency used for the order String 3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/wiki/ISO_4217.
VATInclusivePricing Optional NA Flag that indicates whether the item amount in the quote includes VAT Boolean true or false
CustomerTaxId Optional NA User-defined customer tax ID for the transaction or line item String Max 40 characters
BillingInformation Required NA Reference to the customer's billing information IDREF Through IDREF, references another element in the message
Shipping Required Required Information about all shipping groups and destinations in the order ComplexType Includes: ShipGroups, Destinations
ShipGroups Required Optional Information about all shipping groups in the order ComplexType Includes: ShipGroup (multiple)
TaxTransactionId NA Optional Specifies the transaction ID for the tax quote call. This value can be used later when calling other APIs, such as Order Create Request. String  
ShipGroup
ShipGroup Required Required Information about a specific shipping group in the order ComplexType

Includes attributes: id, taxDutyDisplayPrefCode, chargeType

Includes: DestinationTarget, Items, Gifting
id Required Required Unique identifier for the shipping group String Attribute element; max 12 characters
taxDutyDisplayPrefCode NA Optional Code used to display tax and duty consistently across all downstream systems String

Attribute element with possible values:

CONSOLIDATED_TAXES_ONLY

INDIVIDUAL_TAXES_ONLY

NO_TAXES_OR_DUTIES

chargeType Optional Optional Type of shipping charge (for example, FLAT, WEIGHT) for the shipping group String Attribute element; no restrictions
DestinationTarget Required Required Reference to information about the destination target IDREF Through IDREF, references another element in the message
Items Required Required Information about all items in the shipping group ComplexType Includes: OrderItem (multiple)
Gifting Optional Optional Pricing information if the shipping group is a gift ComplexType

Includes attribute: id

Includes: ItemId, ItemDesc, Pricing
OrderItem
OrderItem Required Required Information about a specific item in the shipping group ComplexType

Includes attribute: lineNumber

Includes: ItemId, ItemDesc, HTSCode, ScreenSize, Origins, Quantity, Pricing, Gifting, Customization
lineNumber Required Required Item line number String Attribute element; no restrictions
ItemId Required Required Identifier for the item (SKU) String Max 20 characters
ItemDesc Optional Optional Description of the item String Max 20 characters
HTSCode Optional Optional Harmonized Tariff Schedule (HTS) code used for calculating duty; required if duty calculation is desired String Max 20 characters
ScreenSize Optional Optional Screen size (in inches) of electronic devices such as televisions. Drives the Vertex calculations for the environment handling fee (EHF) in Canada and California. Value is set as flexible number field 1 on the Tax Quote and Invoice requests. String Max 20 characters
Origins Required NA Information about the store and manufacturer of the item ComplexType Includes: AdminOrigin, ShippingOrigin, ManufacturingCountryCode
Quantity Required Required Quantity of the item in the order Int No restrictions
Pricing Required Required Pricing information for the item ComplexType Includes: Merchandise, Shipping, Duty, Fees
Gifting Optional Optional Pricing information if the item is a gift ComplexType

Includes attribute: id

Includes: Amount, TaxClass, TaxData, PromotionalDiscounts, UnitPrice
Customization Optional Optional Pricing information for all custom features applied to the item ComplexType Includes: Customer Feature List, BasePrice
Origins
Origins Required NA Information about the store and manufacturer of the item ComplexType Includes: AdminOrigin, ShippingOrigin, ManufacturingCountryCode
AdminOrigin Required NA Address of the administrative (business) office, order taking location, order acceptance location, or principle negotiation location of the webstore ComplexType Includes: Line1, Line2, Line3, Line4, BuildingName, PoBox, City, MainDivision, MainDivisionCode, CountryName, CountryCode, PostalCode
ShippingOrigin Required NA Address from which the item is expected to ship ComplexType Includes: Line1, Line2, Line3, Line4, BuildingName, PoBox, City, MainDivision, MainDivisionCode, CountryName, CountryCode, PostalCode
ManufacturingCountryCode Optional NA Country where the item was manufactured or underwent the most significant manufacturing process String 2 through 40 characters
Pricing
Pricing Required Required Pricing information for the item ComplexType Includes: Merchandise, Shipping, Duty, Fees
Merchandise Required Required Price for the item merchandise ComplexType Includes: Amount, TaxClass, TaxData, PromotionalDiscounts, UnitPrice
Shipping Optional Optional Price for shipping the item ComplexType Includes: Amount, TaxClass, TaxData, PromotionalDiscounts
Duty Optional Optional Duty tax for the item ComplexType Includes: Amount, TaxClass, TaxData, PromotionalDiscounts, CalculationError
CalculationError Optional Optional Specific error message related to internal duty calculation String No restrictions
Fees Optional Optional Fees for the item ComplexType Includes: Fee (multiple)
Gifting
Gifting Optional Optional Pricing information if the item is a gift ComplexType

Includes attribute: id

Includes: ItemId, ItemDesc, Pricing
id Optional Optional Unique identifier for the gift item String Attribute element; max 12 characters
ItemId Required Required Identifier for the item (SKU) String Max 20 characters
ItemDesc Optional Optional Description of the item String Max 20 characters
Pricing Required Required Pricing information for the gift item ComplexType Includes: Amount, TaxClass, PromotionalDiscounts, UnitPrice
Customization
Customization Optional Optional Price information for all custom features applied to the item ComplexType Includes: CustomFeatureList, BasePrice
CustomFeatureList Required Required List of each custom feature and its associated upcharge ComplexType

Includes: CustomFeature (multiple)
CustomFeature Required Required Information about a specific custom feature for the item ComplexType

Includes attribute: id

Includes: CustomizationId, ItemId, ItemDesc, Upcharge
id Optional Optional Unique identifier for the custom feature String Attribute element; max 12 characters
CustomizationId Optional Optional Optional value used to group custom features into logical sets String Max 12 characters
ItemId Optional Optional Unique identifier for the custom feature (SKU) String Max 20 characters
ItemDesc Optional Optional Description of the custom feature String Max 20 characters
Upcharge Optional Optional Charge for the custom feature ComplexType Includes: Amount, TaxClass, TaxData, PromotionalDiscounts, UnitPrice
BasePrice Optional Optional Base customization price for the item String Includes: Amount, TaxClass, Tax Data, Promotional Discounts, UnitPrice
Destinations
Destinations Required Required Destination addresses for the order ComplexType Occurs only once. Includes: MailingAddress, EmailAddress
MailingAddress Optional Optional Mailing address for the order ComplexType

Includes attribute: id

Includes: PersonName, Address
id Required Required Unique identifier for the mailing address String Attribute element; max 12 characters
PersonName Required Required Name of the addressee ComplexType Includes: Honorific, LastName, MiddleName, FirstName
Address Required Required Destination address ComplexType Includes: Line1, Line2, Line3, Line4, BuildingName, PoBox, City, MainDivision, MainDivisionCode, CountryName, CountryCode, PostalCode
Email Optional Optional Email address associated with the order ComplexType

Includes attribute: id

Includes: Customer, EmailAddress
id Required Required Unique identifier for the email address String Attribute element; max 12 characters
Customer Optional Optional Name associated with the email address ComplexType Includes: Honorific, LastName, MiddleName, FirstName
EmailAddress Required Required Email address of the addressee String Max 70 characters
Fees
Fees Optional Optional Fees for the item ComplexType Includes: Fee (multiple)
Fee Required Required Information about a specific fee for the item ComplexType Includes: FeeType, Description, FeeId, Charge
FeeType Required Required Type of fee (for example, geographicalSurcharge, importSurchage) String No restrictions
Description Required Required Description of the fee (for example, CA Recycling Fee $18.00) String No restrictions
FeeId Required Required ID for the fee. Item ID is used for any legal fees offered in the output. String No restrictions
Charge Required Required Amount of the fee ComplexType Includes: Amount, TaxClass, TaxData, PromotionalDiscounts
TaxData
TaxData NA Optional Associated tax information ComplexType Includes: TaxClass, Taxes
TaxClass Optional Optional Tax class used for calculating taxes. Default tax class for shipping is 93000. Default tax class for fees is 89999. String Max 40 characters
Taxes NA Optional Information about associated taxes ComplexType Includes: Tax (multiple)
Tax NA Optional Information about a specific tax Complextype

Includes attributes: taxType, taxability

Includes: Situs, Jurisdiction, Imposition, EffectiveRate, TaxableAmount, NonTaxableAmount, CalculatedTax, SellerRegistrationId, InvoiceTextCodes
taxType NA Required System-determined tax type String

Attribute element with possible values:

SALES

SELLER_USE

CONSUMERS_USE

VAT

IMPORT_VAT

NONE

taxability NA Required System-determined taxable status, based on situs and item type String

Attribute element with possible values:

TAXABLE

NONTAXABLE

EXEMPT

DPPAPPLIED

NO_TAX

DEFERRED

Situs NA Optional Situs or tax location, as determined by the calculation engine String No restrictions
Jurisdiction NA Optional Jurisdiction to which the tax is applied String

Includes attributes: jurisdictionLevel, jurisdictionId

No restrictions
jurisdictionLevel NA Required Jurisdiction's common classification, based on its geopolitical and/or taxing context String

Attribute element with the following values:

APO
BOROUGH
CITY
COUNTRY
COUNTY
DISTRICT
FPO
PARISH
PROVINCE
SPECIAL_PURPOSE_DISTRICT
STATE
TERRITORY
TOWNSHIP
TRADE_BLOCK
TRANSIT_DISTRICT

jurisdictionId NA Required Jurisdiction code assigned by the relevant governmental authority String Attribute element; no restrictions
Imposition NA Optional Name of the imposition to which the relevant tax rule belongs String

Includes attribute: impositionType

No restrictions
impositionType NA Required Category of the tax (for example, General Sales and Use Tax, Surcharge, VAT) String Attribute element; no restrictions
EffectiveRate NA Optional

For buyer input tax and seller import tax - Rate is based on the extended price and tax amount (import or input) passed in the request message. If you total the extended price and tax amounts before passing them in the request message, this rate is an average.

For all other tax types - Effective rate the system uses to calculate the tax

 Decimal 2 precision points (for example, 4.05)
TaxableAmount NA Optional Amount that is subject to tax due to taxable status Decimal 2 precision points (for example, 4.05)
nonTaxableAmount NA Optional Amount that is not subject to tax due to nontaxable status Decimal 2 precision points (for example, 4.05)
CalculatedTax NA Optional Amount of the tax calculated by the calculation engine Decimal 2 precision points (for example, 4.05)
SellerRegistrationId NA Optional Registration ID for the seller associated with this item tax Strong No restrictions
InvoiceTextCodes NA Optional All invoice text codes associated with the item ComplexType Includes: InvoiceTextCode (multiple)
InvoiceTextCode NA Optional Specific text code associated with the item String No restrictions
PromotionalDiscounts
PromotionalDiscounts Optional Optional Associated promotional discounts ComplexType Includes: Discount (multiple)
Discount Required Required Specific promotional discount ComplexType

Includes attributes: id, calculateDuty

Includes: Amount
id Optional Optional Unique identifier for the promotional discount String Attribute element; max 12 characters
calculateDuty Optional Optional Flag that indicates whether duty needs to be calculated for the discount Boolean true or false
Amount Required Required Amount used to calculate the discount Decimal 2 precision points (for example, 123.34)
Common (Shared) Fields
Amount Required Required Amount used to calculate taxes Decimal 2 precision points (for example, 123.34)
UnitPrice Required Required Unit price for the item Decimal 2 precision points (for example, 123.34)

Honorific

 Optional Optional Salutation of the payer String Max 10 characters.
LastName Required Required Last name of the payer String Max 64 characters.
MiddleName Optional Optional Middle name of the payer String Max 40 characters.
FirstName Required Required First name of the payer String Max 64 characters.
Line1 Required Required Line 1 of the address String No restrictions
Line2 Optional Optional Line 2 of the address String No restrictions
Line3 Optional Optional Line 3 of the address String No restrictions
Line4 Optional Optional Line 4 of the address String No restrictions
BuildingName Optional Optional Name of the building String No restrictions
PoBox Optional Optional PO box number String No restrictions
City Required Required City String Max 40 characters
MainDivision Optional Optional State, province, or territory String No restrictions
MainDivisionCode Optional Optional Two- or three-digit postal abbreviation for the state, province, or territory String Max 35 characters. ISO 3166-2 code is recommended but not required.
CountryName Optional Optional Country name String No restrictions
CountryCode Required Required Country code String Between 2 and 40 characters. ISO 3166 alpha 2 code is recommended but not required.
PostalCode Optional Optional Postal code String Max 15 characters

Fault Responses

Invalid XML

<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <CreateTimestamp>2011-07-23T20:07:39+00:00</CreateTimestamp>
   <Code>INVALID_XML</Code>
   <Description>The xml submitted for quote request was invalid.</Description>
</Fault>

Internal Error

<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <CreateTimestamp>2011-07-23T20:07:39+00:00</CreateTimestamp>
   <Code>INTERNAL_ERROR</Code>
   <Description>There was an internal server error.</Description>
</Fault>
  
<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <CreateTimestamp/>
   <Code>INTERNAL_ERROR</Code>
   <Description>Vertex call failed. With error: An error occurred while calculating tax on transaction
   identified by "1". This may be an incorrect use of the calculation engine. Please contact your 
   software vendor. Error trying to calculate tax on transaction identified by (1). Unknown country. 
   Expecting an ISO Country Code - Alpha 3 (e.g., USA), or a well-known country name (e.g., United States 
   of America). (country=AA) </Description>
</Fault>

<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <CreateTimestamp/>
   <Code>INTERNAL_ERROR</Code>
   <Description>Discount found more than the amount. Please check your request for accuracy.</Description>
</Fault>

Invalid Request

<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <CreateTimestamp>2015-08-20T17:18:29+00:00</CreateTimestamp>
   <Code>InvalidRequestXmlException</Code>
   <Description>cvc-complex-type.2.4.a: Invalid content was found starting with element 
   'CurrencyConversionRate'. One of '{"http://api.gsicommerce.com/schema/checkout/1.0":Currency}' 
   is expected.</Description>
</Fault>

<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <CreateTimestamp>2015-08-20T17:18:18+00:00</CreateTimestamp>
   <Code>InvalidRequestXmlException</Code>
   <Description>The element type "Currency" must be terminated by the matching end-tag "</Currency>".</Description>
</Fault>

<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <CreateTimestamp>2015-08-20T17:16:43+00:00</CreateTimestamp>
   <Code>InvalidRequestXmlException</Code>
   <Description>cvc-enumeration-valid: Value 'USDx' is not facet-valid with respect to enumeration '
   [AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, 
   BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, 
   EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, GWP, HKD, HNL, HRK, HTG, HUF, 
   IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, 
   LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, 
   NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, 
   SBD, SCR, SDG, SEK, SGD, SHP, SKK, SLL, SOS, SRD, STD, SVC, SYP, SZL, THB, TJS, TMM, TND, TOP, TRY, 
   TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VND, VUV, WST, XAF, XCD, XDR, XOF, XPF, YER, ZAR, ZMK, 
   ZWR]'. It must be a value from the enumeration.</Description>
</Fault>