Invoice Integration - Shipping at Header Level

  • Updated

This article details the required elements and calculation changes for including a Shipping charge at the header level of a cXML invoice. This requires new elements in the <InvoiceDetailRequestHeader> and <InvoiceDetailSummary> elements, and changes to the calculations in <Tax> and <GrossAmount>.

 

Prerequisites

  • Audience: Supplier (Technical/Integration)

  • Intent: Understand the structure and calculation of header-level shipping and tax on a cXML invoice.

  • Data: The Shipping Amount and the applicable tax rate.

 

Invoice Detail Header Changes

To include shipping charges, the <InvoiceDetailShipping> element must be included within the <InvoiceDetailRequestHeader>.

 

1. Invoice Detail Shipping (<InvoiceDetailShipping>)

This element contains the shipTo Contact, which specifies the destination address for the goods.

  • If this element is omitted, Unimarket will still process the invoice but will not import any shipping charges, and no error will be generated.

  • This information will appear in the Ship To section on the invoice, in Unimarket.

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

 

Subtotal Amount (<SubtotalAmount>)

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

  • The SubtotalAmount element contains the Money element.

  • Example Subtotal: $40.53.

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

 

Shipping Amount (<ShippingAmount>)

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

  • This contains the Money element.

  • It represents the Shipping Amount without tax for the invoice.

  • Example Shipping Amount: $10.00.

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

 

Tax (<Tax>) 

The <Tax> element contains the Money element and the money element has a currency attribute. 

  • The Description element contains the name of this type of tax. In this example, it would be GST.
  • The <Tax> element now includes the total tax for goods and shipping (<TaxDetail>). 

Tax Detail (<TaxDetail>)

This should be calculated based on TaxableAmount x Tax Rate = TaxAmount. The <TaxDetail> element provides a breakdown of each tax source.

  1. Tax on Goods (purpose="tax"):

    • Calculation: TaxableAmount x Tax Rate = TaxAmount.

    • Example Goods Tax: $40.53 x 0.15 (15%)= $6.0795.

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

 

  1. Tax on Shipping (purpose="shippingTax"):

    • Calculation: ShippingAmount x Tax Rate = TaxAmount.

    • Example Shipping Tax: $10.00 x 0.15 = $1.50.

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

 

  • Total Tax Calculation: Sum of (Tax on Goods + Tax on Shipping).

  • Example Total Tax: $6.0795 + $1.50 = $7.5795.

<Tax>
    <Money currency="NZD">7.5795</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>
</Tax>

 

Gross Amount (<GrossAmount>)

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

The formula for the Gross Amount is updated to include the <ShippingAmount>.

  • Calculation Formula: Subtotal + ShippingAmount + Tax = GrossAmount.

  • Example Calculation: $40.53 + $10.00 + $7.5795 = $58.1095.

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

 

Example of InvoiceDetailSummary with Shipping

This is the completed summary section including all components.

<InvoiceDetailSummary>
    <SubtotalAmount>
        <Money currency="NZD">40.53</Money>
    </SubtotalAmount>
    <ShippingAmount>
        <Money currency="NZD">10.00</Money>
    </ShippingAmount>
    <Tax>
        <Money currency="NZD">7.5795</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>
    </Tax>
    <GrossAmount>
        <Money currency="NZD">58.1095</Money>
    </GrossAmount>
</InvoiceDetailSummary>