Invoice Integration - Shipping & Special Handling at Line Level – Unimarket Helpdesk

Shipping and Special Handling at Line Level

A Shipping charge and a Special Handling charge can be applied to the Invoice at the line level.

This requires a new attribute in the InvoiceDetailLineIndicator element, the InvoiceDetailSummary element and some changes to the calculations in the Tax and GrossAmount elements in the InvoiceDetailSummary.

InvoiceDetailLineIndicator

The InvoiceDetailLineIndicator element must have the isShippingInLine and isSpecialHandlingInLine attributes with both set to "yes".

<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>

InvoiceDetailLineShipping

The InvoiceDetailLineShipping element needs to be included in the InvoiceDetailItem element.

The InvoiceDetailShipping element contains the shipTo Contact which is where the goods were shipped to.

The Money element has a currency attribute and shipping charge for the line without tax.

Note: These elements must be present on each line due to the isShippingInLine indicator.

The Ship To Contact elements can be null. The Money element 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>

This will show only the first Ship To address on the invoice for the customer in the Ship To section on the Invoice in Unimarket.

InvoiceDetailLineSpecialHandling

The InvoiceDetailLineSpecialHandling element needs to be included in the InvoiceDetailItem element.

This contains the Money element.

The Money element has a currency attribute and special handling charge for the line without tax.

Note: These elements must be present on each line due to the isSpecialHandlingInLine indicator.

The Money element can be 0.00

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

SubtotalAmount

The SubtotalAmount element contains the Money element.

The Money element has a currency attribute and the sum total for all lines on the invoice.

In this example it would be: 17.05 + 13.08 + 10.40 = 40.53

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

ShippingAmount

The ShippingAmount element needs to be included in the InvoiceDetailSummary element.

This contains the Money element.

The Money element has a currency attribute and the sum total of the InvoiceDetailLineShipping charge for all lines on the invoice.

In this example it would be: 5.00 + 5.00 + 5.00 = 15.00

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

SpecialHandlingAmount

The SpecialHandlingAmount element needs to be included in the InvoiceDetailSummary element.

This contains the Money element.

The Money element has a currency attribute and the sum total of the InvoiceDetailLineSpecailHandling charge for all lines on the invoice.

In this example it would be: 18.00 + 0.00 + 23.00 = 41.00

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

Tax

The Tax element contains the Money element.

The Money element has a currency attribute and the total tax for goods, shipping and special handling on the invoice.

The Description element contains the name of this type of tax. In this example it would be GST.

The TaxDetail element contains a further breakdown showing each tax source.

TaxDetail

In the below example you can see the Tax on Goods (purpose="tax"), the Tax on Shipping (purpose="shippingTax") and the Tax on Special Handling (purpose="specialHandlingTax").

This should be calculated based on TaxableAmount x Tax Rate = TaxAmount

Goods:

In this example it would be: 40.53 x 0.15 (15%) = 6.0795

The purpose attribute is "tax".

The Description element contains the name of this type of tax. In this example it would be GST.

<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>

Shipping:

In this example it would be: 15.00 x 0.15 (15%) = 2.25

The purpose attribute is "shippingTax".

The Description element contains the name of this type of tax. In this example it would be GST.

<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>

Special Handling:

In this example it would be: 41.00 x 0.15 (15%) = 6.15

The purpose attribute is "specialHandlingTax".

The Description element contains the name of this type of tax. In this example it would be GST.

<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>

In this example it would be:

6.0795 (Tax on Goods) + 2.25 (Tax on Shipping) + 6.15 (Tax on Special Handling) = 14.4795

<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>

GrossAmount

The GrossAmount element contains the Money element.

The Money element has a currency attribute and the Gross Amount for the invoice.

This should be calculated based on Subtotal + ShippingAmount + SpecialHandlingAmount + Tax = GrossAmount

In this example it would be: 40.53 + 10.00 + 41.00 + 14.4795 = 111.0095

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

InvoiceDetailSummary

Below is the example InvoiceDetailSummary section including 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">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>