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.
Copy
<?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 |
| 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
Copy
<?xml version="1.0" encoding="UTF-8"?>
<AckReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<Received/>
</AckReply>Fault Responses
Invalid XML
Copy
<?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
Copy
<?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
Copy
<?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>