This article details the elements and calculation changes required. To include both Shipping and Special Handling charges at the header level of a cXML invoice. This method requires adding new elements to the <InvoiceDetailRequestHeader> and <InvoiceDetailSummary>.
Prerequisites
Audience: Supplier (Technical/Integration)
Intent: Understand the structure and calculation of header-level shipping and special handling, including associated tax, on a cXML invoice.
Data: Shipping Amount, Special Handling Amount, and the applicable tax rate.
1. Invoice Detail Shipping (<InvoiceDetailShipping>)
The <InvoiceDetailShipping> element must be included in the <InvoiceDetailRequestHeader>. This element contains the shipTo Contact information, which indicates where the goods were shipped.
<InvoiceDetailRequestHeader invoiceDate="2020-10-08" invoiceID="TestInvoice10020" operation="new" purpose="standard">
<InvoiceDetailLineIndicator isTaxInLine="yes"/>
<InvoicePartner>
<Contact role="billTo">
<Name lang="en">Head Office</Name>
<PostalAddress>
<Street>123 Something Street</Street>
<City>Auckland</City>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
</Contact>
</InvoicePartner>
<InvoiceDetailShipping>
<Contact role="shipTo">
<Name lang="en">Customers Address</Name>
<PostalAddress>
<Street>456 Another Ave</Street>
<City>Auckland</City>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
</Contact>
</InvoiceDetailShipping>
</InvoiceDetailRequestHeader>2. Header-Level Charges in Summary
The <InvoiceDetailSummary> must be updated to include both the shipping and special handling amounts.
Note: Freight charges are typically entered in the Shipping field. Special Handling covers additional charges beyond shipping/freight (e.g., gas fuel surcharge, for live specimens, tariff charges).
| Element | Calculation / Value | Example Value |
|---|---|---|
<SubtotalAmount> | Sum total for all line items on the invoice. | $40.53 |
<ShippingAmount> | Shipping Amount without tax for the invoice. | $10.00 |
<SpecialHandlingAmount> | Special Handling Amount without tax for the invoice. | $25.00 |
<SubtotalAmount> Example:
<SubtotalAmount>
<Money currency="NZD">40.53</Money>
</SubtotalAmount><ShippingAmount> Example:
<ShippingAmount>
<Money currency="NZD">10.00</Money>
</ShippingAmount><SpecialHandlingAmount>
<SpecialHandlingAmount>
<Money currency="NZD">25.00</Money>
</SpecialHandlingAmount>3. Tax and Tax Detail Calculations
The <Tax> and <GrossAmount> elements are updated to include all three taxable base amounts (Goods, Shipping, and Special Handling).
Total Tax (<Tax>)
The total tax is the sum of the calculated tax amounts for Goods, Shipping, and Special Handling.
Example Calculation: $6.0795 + $1.50 + $3.75 = $11.3295.
<Tax>
<Money currency="NZD">11.3295</Money>
<Description lang="en">GST</Description>
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">40.53</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">6.0795</Money>
</TaxAmount>
<Description lang="en">GST</Description>
</TaxDetail>
<TaxDetail category="GST" percentageRate="15.00" purpose="shippingTax">
<TaxableAmount>
<Money currency="NZD">10.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">1.50</Money>
</TaxAmount>
<Description lang="en">GST</Description>
</TaxDetail>
<TaxDetail category="GST" percentageRate="15.00" purpose="specialHandlingTax">
<TaxableAmount>
<Money currency="NZD">25.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">3.75</Money>
</TaxAmount>
<Description lang="en">GST</Description>
</TaxDetail>
</Tax>
Tax Detail (<TaxDetail>)
Tax Detail is calculated based on the formula: TaxableAmount x Tax Rate = TaxAmount.
The <TaxDetail> element contains a breakdown for each source.
| Tax Source | Purpose Attribute | Taxable Amount | Example Calculation (15% Rate) |
|---|---|---|---|
| Goods | "tax" | Subtotal Amount ($40.53) | $40.53 x 0.15 = $6.0795 |
| Shipping | "shippingTax" | Shipping Amount ($10.00) | $10.00 x 0.15 = $1.50 |
| Special Handling | "specialHandlingTax" | Special Handling Amount ($25.00) | $25.00 x 0.15 = $3.75 |
Gross Amount (<GrossAmount>)
The formula for the Gross Amount is updated to include the <ShippingAmount> and <SpecialHandlingAmount>.
Calculation Formula: Subtotal + ShippingAmount + SpecialHandlingAmount + Tax = GrossAmount.
Example Calculation: $40.53 + $10.00 + $25.00 + $11.3295 = $86.8595.
<GrossAmount>
<Money currency="NZD">86.8595</Money>
</GrossAmount>
Example: InvoiceDetailSummary with Shipping and Special Handling
<InvoiceDetailSummary>
<SubtotalAmount>
<Money currency="NZD">40.53</Money>
</SubtotalAmount>
<ShippingAmount>
<Money currency="NZD">10.00</Money>
</ShippingAmount>
<SpecialHandlingAmount>
<Money currency="NZD">25.00</Money>
</SpecialHandlingAmount>
<Tax>
<Money currency="NZD">11.3295</Money>
<Description lang="en">GST</Description>
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">40.53</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">6.0795</Money>
</TaxAmount>
<Description lang="en">GST</Description>
</TaxDetail>
<TaxDetail category="GST" percentageRate="15.00" purpose="shippingTax">
<TaxableAmount>
<Money currency="NZD">10.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">1.50</Money>
</TaxAmount>
<Description lang="en">GST</Description>
</TaxDetail>
<TaxDetail category="GST" percentageRate="15.00" purpose="specialHandlingTax">
<TaxableAmount>
<Money currency="NZD">25.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">3.75</Money>
</TaxAmount>
<Description lang="en">GST</Description>
</TaxDetail>
</Tax>
<GrossAmount>
<Money currency="NZD">86.8595</Money>
</GrossAmount>
</InvoiceDetailSummary>