Invoice Integration - Shipping & Special Handling at Line Level

  • Updated

This guide outlines the cXML requirements for applying Shipping and Special Handling charges at the individual line item level of an invoice. This approach requires updating the InvoiceDetailLineIndicator and modifying the calculations within the InvoiceDetailSummary.

 

Notes

  • Shipping: Typically used for freight or general delivery charges.

  • Special Handling: Used for additional costs beyond standard shipping/freight (e.g., gas fuel surcharge, tariff charges, live specimen handling).

 

1. InvoiceDetailLineIndicator

The InvoiceDetailLineIndicator element must be included in the InvoiceDetailRequestHeader with two new attributes set to "yes".

AttributeValuePurpose
isShippingInLine"yes"Indicates that shipping charges will be present at the line item level.
isSpecialHandlingInLine"yes"Indicates that special handling charges will be present at the line item level.

Example InvoiceDetailRequestHeader:

<InvoiceDetailRequestHeader invoiceDate="2020-10-08" invoiceID="TestInvoice10025" operation="new" purpose="standard">
   <InvoiceDetailLineIndicator isTaxInLine="yes" isShippingInLine="yes" isSpecialHandlingInLine="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>
</InvoiceDetailRequestHeader>

 

2. InvoiceDetailLineSpecialHandling

Due to the header indicator, the following elements must be present on each line (InvoiceDetailItem), even if the charges are 0.00.

 

A. InvoiceDetailLineShipping

This element captures the shipping charge for a specific line item.

  • <InvoiceDetailShipping>: Includes the shipTo contact details, which should reflect where the goods were shipped.

  • Note: Unimarket will display only the first Ship To address on the invoice in the supplier store.

  • <Money>: The shipping charge for the line, excluding tax. Can be 0.00.

 
<InvoiceDetailLineShipping>
    <InvoiceDetailShipping>
        <Contact role="shipTo">
            <Name lang="en">First Customers Address</Name>
            <PostalAddress>
                <Street>456 Another Ave</Street>
                <City>Auckland</City>
                <PostalCode>1010</PostalCode>
                <Country isoCountryCode="NZ">New Zealand</Country>
            </PostalAddress>
        </Contact>
    </InvoiceDetailShipping>
    <Money currency="NZD">5.00</Money>
</InvoiceDetailLineShipping>

 

B. InvoiceDetailLineSpecialHandling

This element captures the special handling charge for a specific line item.

  • <Money>: The special handling charge for the line, excluding tax. Can be 0.00.

 
<InvoiceDetailLineSpecialHandling>
    <Money currency="NZD">18.00</Money>
</InvoiceDetailLineSpecialHandling>

 

3. InvoiceDetailSummary

The summary section must be updated to include the total sums of the line-level charges and correctly calculate the tax and gross amount.

Assume the following totals for line items (from the provided example):

  • Line Subtotals: $40.53

  • Line Shipping: $15.00

  • Line Special Handling: $41.00

  • Tax Rate: 15%

 

InvoiceDetailSummary Example

<InvoiceDetailSummary>
    <SubtotalAmount>
        <Money currency="NZD">40.53</Money>
    </SubtotalAmount>
    <ShippingAmount>
        <Money currency="NZD">10.00</Money>
    </ShippingAmount>
    <SpecialHandlingAmount>
        <Money currency="NZD">41.00</Money>
    </SpecialHandlingAmount>
    <Tax>
        <Money currency="NZD">14.4795</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">41.00</Money>
            </TaxableAmount>
            <TaxAmount>
                <Money currency="NZD">6.15</Money>
            </TaxAmount>
            <Description lang="en">GST</Description>
        </TaxDetail>
    </Tax>
    <GrossAmount>
        <Money currency="NZD">111.0095</Money>
    </GrossAmount>
</InvoiceDetailSummary>

 

A. SubtotalAmount (Goods Only)

The sum of the subtotals for all lines.

  • Example Calculation: $17.05 + $13.08 + $10.40 = $40.53

 
<SubtotalAmount>
    <Money currency="NZD">40.53</Money>
</SubtotalAmount>

 

B. ShippingAmount

The sum total of the InvoiceDetailLineShipping charge for all lines.

  • Example Calculation: $5.00 + $5.00 + $5.00 = $15.00

 
<ShippingAmount>
    <Money currency="NZD">15.00</Money>
</ShippingAmount>

 

C. SpecialHandlingAmount

The sum total of the InvoiceDetailLineSpecialHandling charge for all lines.

  • Example Calculation: $18.00 + $0.00 + $23.00 = $41.00

 
<SpecialHandlingAmount>
    <Money currency="NZD">41.00</Money>
</SpecialHandlingAmount>

 

D. Tax (Full Breakdown)

The total tax must be the sum of tax calculated on the goods, shipping, and special handling. The TaxDetail element must be repeated for each purpose.

PurposeTaxable Amount (from Summary)Tax RateCalculated Tax Amount
tax (Goods)$40.5315%$6.0795
shippingTax$15.0015%$2.25
specialHandlingTax$41.0015%$6.15
Total Tax  $14.4795

Example Tax Element:

<Tax>
    <Money currency="NZD">14.4795</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">15.00</Money>
        </TaxableAmount>
        <TaxAmount>
            <Money currency="NZD">2.25</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>

 

E. GrossAmount

The total value of the invoice.

  • Calculation: Subtotal + ShippingAmount + SpecialHandlingAmount + Tax = GrossAmount

  • Example Calculation: $40.53 + $15.00 + $41.00 + $14.4795 = $111.0095

 
<GrossAmount>
    <Money currency="NZD">111.0095</Money>
</GrossAmount>