TDF Tax Distribute

Overview

The order management system calls the TDF Tax Distribute operation to perform the following processing:

  • Account for tax credits.
  • Distribute tax credits for any adjustments.
  • Record tax credit details for legal and reporting purposes.

This asynchronous operation creates a distribute request (TaxDistributeRequest) on the Tax Service and returns an acknowledgment (AckReply).

URI Summary

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

Schemas

Request Example

The request is a TaxDistributeRequest message.

<?xml version="1.0" encoding="UTF-8"?>
<TaxDistributeRequest  xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <OrderId>0001200001234502</OrderId>
   <OriginalOrderId>0001200001234500</OriginalOrderId>
   <WebOrderNumber>00145678908</WebOrderNumber>
   <InvoiceNumber>42374659867655665</InvoiceNumber>
   <OrderDateTime>2014-01-30T14:58:08.707Z</OrderDateTime>
   <OriginalOrderDateTime>2014-01-29T14:58:08.707Z</OriginalOrderDateTime>
   <ShipDateTime>2014-01-31T14:58:08.707Z</ShipDateTime>
   <Currency>USD</Currency>
   <CurrencyConversionRate>1.00</CurrencyConversionRate>
   <VATInvoiceNumber>12456</VATInvoiceNumber>
   <CustomerTaxId>12345</CustomerTaxId>
   <BillingInformation ref="bill_dest_1"/>
   <!--Optional:-->
   <Shipping>
      <ShipGroups>
         <ShipGroup chargeType="FLATRATE" id="shipgroup_1">
            <DestinationTarget ref="dest_1"/>
            <Items>
               <OrderItem lineNumber="1">
                  <ItemId>123457175304</ItemId>
                  <ItemDesc>Product Description</ItemDesc>
                  <HTSCode>1234.12.1234</HTSCode>
                  <VendorPartNumber>TDF7889</VendorPartNumber>
                  <ShippingCartonId>1XZ4556</ShippingCartonId>
                  <Origins>
                     <AdminOrigin>
                        <Line1>935 1st Ave</Line1>
                        <City>King Of Prussia</City>
                        <MainDivisionCode>PA</MainDivisionCode>
                        <CountryCode>US</CountryCode>
                        <PostalCode>19406</PostalCode>
                     </AdminOrigin>
                     <ShippingOrigin>
                        <Line1>4 Whatever Rd</Line1>
                        <City>Louisville</City>
                        <MainDivisionCode>KY</MainDivisionCode>
                        <CountryCode>US</CountryCode>
                        <PostalCode>40258</PostalCode>
                     </ShippingOrigin>
                     <ManufacturingCountryCode>US</ManufacturingCountryCode>
                  </Origins>
                  <Quantity>1</Quantity>
                  <TaxCreditAmount>-5.00</TaxCreditAmount>
               </OrderItem>
               <OrderItem lineNumber="2">
                  <ItemId>123457175303</ItemId>
                  <ItemDesc>Product Description 2</ItemDesc>
                  <HTSCode>1234.12.1234</HTSCode>
                  <VendorPartNumber>TDF7888</VendorPartNumber>
                  <ShippingCartonId>1XZ4556</ShippingCartonId>
                  <Origins>
                     <AdminOrigin>
                        <Line1>935 1st Ave</Line1>
                        <City>King Of Prussia</City>
                        <MainDivisionCode>PA</MainDivisionCode>
                        <CountryCode>US</CountryCode>
                        <PostalCode>19406</PostalCode>
                     </AdminOrigin>
                     <ShippingOrigin>
                        <Line1>4 Whatever Rd</Line1>
                        <City>Louisville</City>
                        <MainDivisionCode>KY</MainDivisionCode>
                        <CountryCode>US</CountryCode>
                        <PostalCode>40258</PostalCode>
                     </ShippingOrigin>
                     <ManufacturingCountryCode>CA</ManufacturingCountryCode>
                  </Origins>
                  <Quantity>1</Quantity>
                  <TaxCreditAmount>-25.00</TaxCreditAmount>
               </OrderItem>
            </Items>
         </ShipGroup>
      <ShipGroups>
      <Destinations>
         <MailingAddress id="dest_1">
            <PersonName>
               <!--Optional:-->
               <Honorific>Mr</Honorific>
               <LastName>LastName1</LastName>
               <!--Optional:-->
               <MiddleName>MiddleName1</MiddleName>
               <FirstName>FirstName1</FirstName>
               <!--You may enter ANY elements at this point-->
               <!--<AnyElement/>-->
            </PersonName>
            <Address>
               <Line1>123 Elm</Line1>
               <Line2>Line 2</Line2>
               <Line3>Line 3</Line3>
               <City>Philadelphia</City>
               <MainDivisionCode>PA</MainDivisionCode>
               <CountryCode>US</CountryCode>
               <PostalCode>19128</PostalCode>
            </Address>
         </MailingAddress>
         <MailingAddress id="bill_dest_1">
            <PersonName>
               <!--Optional:-->
               <Honorific>Dr</Honorific>
               <LastName>LastName2</LastName>
               <!--Optional:-->
               <MiddleName>MiddleName2</MiddleName>
               <FirstName>FirstName2</FirstName>
               <!--You may enter ANY elements at this point-->
               <!--<AnyElement/>-->
            </PersonName>
            <Address>
               <Line1>630 Allendale Rd</Line1>
               <Line2>Line 2</Line2>
               <Line3>Line 3</Line3>
               <City>King Of Prussia</City>
               <MainDivisionCode>PA</MainDivisionCode>
               <CountryCode>US</CountryCode>
               <PostalCode>19406</PostalCode>
            </Address>
         </MailingAddress>
      </Destinations>
   </Shipping>
   <Fees>
      <Fee>
         <FeeType>ConvenienceStoreSurcharge</FeeType>
         <Description>Payment Convenience Store Surcharge</Description>
         <TaxCreditAmount>-7.00</TaxCreditAmount>
      </Fee>
   </Fees>
</TaxDistributeRequest>

Request Data Elements

Element Required Description Type Restriction
StoreId Yes Store ID used in the URL String Max 20 characters
OrderId Yes Unique identifier for the order managed through the order management system String Max 30 characters
OriginalOrderId Yes Unique identifier for the original order associated with this transaction managed through order management system String Max 30 characters
WebOrderNumber No Webstore order number String Max 40 characters
InvoiceNumber Yes Invoice number associated with this transaction managed through order management system String Max 30 characters
OrderDateTime Yes Date and time of the order DateTime YYYY-MM-DDTHH:MM:SS.SSSZ
OriginalOrderDateTime Yes Date and time of the original order DateTime YYYY-MM-DDTHH:MM:SS.SSSZ
ShipDateTime Yes Date and time when the order was shipped DateTime YYYY-MM-DDTHH:MM:SS.SSSZ
Currency Yes 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.
CurrencyConversionRate No Identifier for the currency conversion rate String No restrictions
VATInvoiceNumber No VAT invoice number, if applicable String Max 20 characters, no white spaces
CustomerTaxId No User-defined customer tax ID for the transaction or line item. Mainly used to identify tax exempt status for the customer. String Max 40 characters
BillingInformation Yes Reference to the customer's billing information IDREF Through IDREF, references another element in the message
Shipping Yes Information about all shipping groups and destinations in the order ComplexType Includes: ShipGroups, Destinations
ShipGroups No Information about all shipping groups in the order ComplexType Includes: ShipGroup (multiple)
ShipGroup
ShipGroup Yes Information about a specific shipping group in the order ComplexType

Includes attributes: id, chargeType

Includes: DestinationTarget, Items, Gifting

id Yes Unique identifier for the shipping group String Attribute element; max 12 characters
chargeType No Type of shipping charge (for example, FLAT, WEIGHT) for the shipping group String Attribute element; no restrictions
DestinationTarget Yes Reference to information about the destination target IDREF Through IDREF, references another element in the message
Items Yes Information about all items in the shipping group ComplexType Includes: OrderItem (multiple)
Gifting No Gifting information for the shipping group ComplexType Includes: ItemId, ItemDesc, VendorPartNumber, ShippingCartonId, TaxCreditAmount
OrderItem
OrderItem Yes Information about a specific item in the shipping group ComplexType

Includes attribute: lineNumber

Includes: ItemId, ItemDesc, HTSCode, VendorPartNumber, ShippingCartonId, LocationCode, Origins, Quantity, TaxCreditAmount

lineNumber Yes Item line number String Attribute element; no restrictions
ItemId Yes Identifier for the item (SKU) String Max 20 characters
ItemDesc Optional Description of the item String Max 20 characters
HTSCode Yes Harmonized Tariff Schedule (HTS) code used for calculating duty; required if duty calculation is desired String No restrictions
VendorPartNumber No Identifier for the vendor product number String No restrictions
ShippingCartonId No Shipping carton ID String No restrictions
LocationCode No Value that can be used for filing a tax return in jurisdictions that require tax filing for individual retail locations String Max 20 characters
Origins Yes Information about the store and manufacturer of the item ComplexType Includes: AdminOrigin, ShippingOrigin, ManufacturingCountryCode
Quantity Yes Quantity of the item in the order Int No restrictions
TaxCreditAmount Yes Tax Credit Amount for adjustment Decimal 2 precision points (for example, -4.20)
Origins
Origins Yes Information about the store and manufacturer of the item ComplexType Includes: AdminOrigin, ShippingOrigin, ManufacturingCountryCode
AdminOrigin Yes 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 Yes Address from which the item is expected to ship ComplexType Includes: Line1, Line2, Line3, Line4, BuildingName, PoBox, City, MainDivision, MainDivisionCode, CountryName, CountryCode, PostalCode
ManufacturingCountryCode No Country where the item was manufactured or underwent the most significant manufacturing process String 2 through 40 characters. ISO 3166 alpha 2 code is recommended.
Gifting
Gifting No Gifting information for the shipping group ComplexType Includes: ItemId, ItemDesc, VendorPartNumber, ShippingCartonId, TaxCreditAmount
ItemId Yes Identifier for the item (SKU) String Max 20 characters
ItemDesc No Description of the item String Max 20 characters
VendorPartNumber No Identifier for the vendor product number String No restrictions
ShippingCartonId No Shipping carton ID String No restrictions
TaxCreditAmount Yes Tax Credit Amount for adjustment decimal 2 precision points (for example, -4.20)
Destinations
Destinations Yes Destination addresses for the order ComplexType Occurs only once. Includes: MailingAddress, Email
MailingAddress
MailingAddress No Mailing address for the order ComplexType

Includes attribute: id

Includes: PersonName, Address

id Yes Unique identifier for the mailing address String Attribute element; max 12 characters
PersonName Yes Name of the addressee Complex Type Includes: Honorific, LastName, MiddleName, FirstName
Honorific No Salutation of the payer String Max 10 characters
LastName Yes Last name of the payer String Max 64 characters
MiddleName No Middle name of the payer String Max 40 characters
FirstName Yes First name of the Payer String Max 64 characters
Address Yes Destination address ComplexType Includes: Line1, Line2, Line3, Line4, BuildingName, PoBox, City, MainDivision, MainDivisionCode, CountryName, CountryCode, PostalCode
Line1 Yes Line 1 of the destination address String No restrictions
Line2 No Line 2 of the destination address String No restrictions
Line3 No Line 3 of the destination address String No restrictions
Line4 No Line 4 of the destination address String No restrictions
BuildingName No Name of the building for the destination address String No restrictions
PoBox No PO box number for the destination address String No restrictions
City Yes City for the destination address String Max 40 characters
MainDivision No Name of the destination state, province, or territory String No restrictions.
MainDivisionCode No Two- or three-digit postal abbreviation for the destination state, province, or territory String Max 35 characters. ISO 3166-2 code is recommended but not required.
CountryName No Name of the destination country String No restrictions
CountryCode Yes Code of the destination country String Between 2 and 40 Characters. ISO 3166 alpha 2 code is recommended but not required.
PostalCode No Destination postal code String Max 15 characters
Email
Email No Email address associated with the order ComplexType

Includes attribute: id

Includes: Customer, EmailAddress

id Yes Unique identifier for the email address String Attribute element; max 12 characters
Customer No Name associated with the email address ComplexType Includes: Honorific, LastName, MiddleName, FirstName.
EmailAddress Yes Email address of the addressee String Max 70 characters
Fees
Fees No Information about all fees for the order ComplexType Includes: Fee (multiple)
Fee Yes Information about a specific fee ComplexType Includes: FeeType, Description, TaxCreditAmount
FeeType Yes Type of fee (for example, geographicalSurcharge, importSurchage) String No restrictions
Description Yes Description of the fee (for example, CA Recycling Fee $18.00) String No restrictions
TaxCreditAmount Yes Tax Credit Amount for adjustment decimal 2 precision points (for example, -4.20)

Success Response

<?xml version="1.0" encoding="UTF-8"?>
<AckReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <Received/>
</AckReply>

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>

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>