Invoice Integration - Shipping at Line Level

  • Updated

This article details the elements and calculation changes required to include a Shipping charge at the line level of a cXML invoice. This method requires a new attribute in the <InvoiceDetailLineIndicator> and updates to the calculations within the <InvoiceDetailSummary>.

 

Prerequisites

  • Audience: Supplier (Technical/Integration)

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

  • Data: Individual line-item shipping charges and the applicable tax rate.

 

1. Invoice Detail Line Indicator (<InvoiceDetailLineIndicator>)

To enable line-level shipping, the isShippingInLine attribute must be added to the <InvoiceDetailLineIndicator> element and set to "yes".

  • When isShippingInLine is set to "yes", the <InvoiceDetailLineShipping> element must be present on each <InvoiceDetailItem>.

 
<InvoiceDetailRequestHeader invoiceDate="2020-10-08" invoiceID="TestInvoice10020" operation="new" purpose="standard">
    <InvoiceDetailLineIndicator isTaxInLine="yes" isShippingInLine="yes"/>
    </InvoiceDetailRequestHeader>

 

2. Invoice Detail Line Shipping (<InvoiceDetailLineShipping>) 

This money element has a currency attribute and includes the shipping charge for the line item without tax.

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

  • It contains the <InvoiceDetailShipping> element, which holds the shipTo Contact information.

    • Note: The <Contact> elements can be null, and the <Money> element can be 0.00.

  • Only the first Ship To address specified across all lines, will show on the invoice in Unimarket.

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

 

Subtotal Amount (<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.

  • Example Subtotal: $17.05 + $13.08 + $10.40 = $40.53.

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

 

Shipping Amount (<ShippingAmount>)

The ShippingAmount contains the Money element.

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

This element represents the sum total of the <InvoiceDetailLineShipping> charges for all lines on the invoice.

  • Calculation: Sum of all <InvoiceDetailLineShipping>/<Money> values.

  • Example Shipping Amount: $5.00 + $5.00 + $5.00 = $15.00.

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

 

Tax (<Tax>) 

The Tax element contains the Money element.

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

The Description element contains the name of this type of tax. In the example below, is it listed as GST.

 

Tax Detail (<TaxDetail>)

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

The total tax is the sum of tax on goods and tax on shipping (TaxableAmount x Tax Rate = TaxAmount).

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

    • Taxable Amount: The overall <SubtotalAmount> ($40.53).

    • Example Goods Tax: $40.53 x 0.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"): 

    • Taxable Amount: The overall <ShippingAmount> ($15.00).

    • Example Shipping Tax: $15.00 x 0.15 = $2.25. (Note: 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>

 

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

    • Example Total Tax: $6.0795 + $2.25 = $8.3295.

<Tax>
    <Money currency="NZD">8.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">15.00</Money>
        </TaxableAmount>
        <TaxAmount>
            <Money currency="NZD">2.25</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 includes the line-level shipping total.

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

  • Example Calculation: $40.53 + $15.00 + $8.3295 = 63.8595.

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

 

InvoiceDetailSummary with Line-Level Shipping Example

<InvoiceDetailSummary>
    <SubtotalAmount>
        <Money currency="NZD">40.53</Money>
    </SubtotalAmount>
    <ShippingAmount>
        <Money currency="NZD">15.00</Money>
    </ShippingAmount>
    <Tax>
        <Money currency="NZD">8.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">15.00</Money>
            </TaxableAmount>
            <TaxAmount>
                <Money currency="NZD">2.25</Money>
            </TaxAmount>
            <Description lang="en">GST</Description>
        </TaxDetail>
    </Tax>
    <GrossAmount>
        <Money currency="NZD">63.8595</Money>
    </GrossAmount>
</InvoiceDetailSummary>