Overview
Invoice Integration uses the cXML standard to allow suppliers to send invoices to Unimarket.
When received the invoice document is validated and passed onto the matching process for the customer.
Errors in the validation will be included in the response. An email is also generated explaining the error and sent to the Invoicing contact listed in the Supplier Profile.
In this Article
Suggested Process for Invoice Integration
Example Basic Invoice Structure
Complete Basic Invoice Example
Shipping and Special Handling at Header Level
Shipping and Special Handling at Line Level
Suggested Process for Invoice Integration
- The Invoice file is generated by the Supplier ERP
- A cXML Invoice file is sent to Unimarket
- Unimarket processes the cXML Invoice message and provides a response
- The supplier processes the response and based on the response code makes a decision:
- 200 Response - The invoice file was successfully processed, no further action required
- 400 Response - The invoice file had errors, please generate a notification to an internal team
- 500 Response - The invoice is unable to be processed, contact support@unimarket.com
| Note: There will also be an email sent for any invoices that fail to the Invoicing Email Address set on the Contact in your store. |
Example Basic Invoice Structure
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.038/InvoiceDetail.dtd">
<cXML payloadID="[A Unique Value]" timestamp="2020-10-08T23:59:45-07:00" version="1.2.021">
<Header>
<From>...</From>
<To>...</To>
<Sender>...</Sender>
</Header>
<Request deploymentMode="test">
<InvoiceDetailRequest>
<InvoiceDetailRequestHeader invoiceDate="2020-10-08" invoiceID="[Invoice Number]" operation="new" purpose="standard">
<InvoiceDetailLineIndicator isTaxInLine="yes"/>
<InvoicePartner>
<Contact role="billTo">...</Contact>
</InvoicePartner>
</InvoiceDetailRequestHeader>
<InvoiceDetailOrder>
<InvoiceDetailOrderInfo>
<OrderReference orderID="[Purchase Order Number]"/>
</InvoiceDetailOrderInfo>
<InvoiceDetailItem invoiceLineNumber="1" quantity="1.00">...</InvoiceDetailItem>
<InvoiceDetailItem invoiceLineNumber="2" quantity="12.00">...</InvoiceDetailItem>
<InvoiceDetailItem invoiceLineNumber="3" quantity="10.00">...</InvoiceDetailItem>
</InvoiceDetailOrder>
<InvoiceDetailSummary>
<SubtotalAmount>...</SubtotalAmount>
<Tax>...</Tax>
<GrossAmount>...</GrossAmount>
</InvoiceDetailSummary>
</InvoiceDetailRequest>
</Request>
</cXML>
cXML Header (Credentials)
The cXML Header validates who is sending the document and who it's being sent to.
- The Header section identifies the Supplier Store
- The To section identifies the Community
- The Sender section identifies the Supplier Integration User
Each section has a Credential domain attribute and Identity.
- The domain attribute for From and To Credentials can be "DUNS", "unimarket-id" or "unimarket-code".
- The domain attribute for the Sender Credential can be "DUNS" or "unimarket-user"
Unimarket will match the Identity credentials supplied with the Supplier and the Customer.
If using a DUNS number this will need to match exactly what has been loaded for the Supplier or Customer.
The unimarket-id, unimarket-code and unimarket-user credentials are supplied by Unimarket.
Example Header (Using DUNS)
<Header>
<From>
<Credential domain="DUNS">
<Identity>1234567890</Identity>
</Credential>
</From>
<To>
<Credential domain="DUNS">
<Identity>0987654321</Identity>
</Credential>
</To>
<Sender>
<Credential domain="DUNS">
<Identity>1234567890</Identity>
<SharedSecret>Super Secret Password</SharedSecret>
</Credential>
<UserAgent>Suppliers Software System</UserAgent>
</Sender>
</Header>
Example Header (Using Unimarket Credentials)
<Header>
<From>
<Credential domain="unimarket-id">
<Identity>82d1aa66-095a-45a8-b8f1-20778aac4ed8</Identity>
</Credential>
</From>
<To>
<Credential domain="unimarket-code">
<Identity>miketest</Identity>
</Credential>
</To>
<Sender>
<Credential domain="unimarket-user">
<Identity>fd36b3b9-ad5a-4fa6-aedd-a826b7b3d87b</Identity>
<SharedSecret>Super Secret Password</SharedSecret>
</Credential>
<UserAgent>Suppliers Software System</UserAgent>
</Sender>
</Header>
Any combination of "DUNS", "unimarket-id", "unimarket-code" or "unimarket-user" can be used for the credential domains.
cXML Request
The Request element contains the deploymentMode attribute and the InvoiceDetailRequest element.
The deploymentMode can be either "test" or "production".
The InvoiceDetailRequest is the invoice that is contained in the message and is made up of 3 sections:
- InvoiceDetailRequestHeader
- InvoiceDetailRequestOrder
- InvoiceDetailSummary
InvoiceDetailRequestHeader
This contains attributes for the invoiceDate, invoiceID, operation, purpose and elements for InvoiceDetailLineIndicator and InvoicePartner.
The invoiceDate is the Invoice Date listed on the invoice
This should be in the format: YYYY-MM-DD. If this is missing then Unimarket will assign the date and time the invoice was received as the Invoice Date.
The invoiceID is the Invoice Number listed on the invoice
The operation will always be "new"
The purpose will always be "standard"
<InvoiceDetailRequestHeader invoiceDate="2020-10-08" invoiceID="TestInvoice10018" operation="new" purpose="standard">
The InvoiceDetailLineIndicator element is used to signify if Tax is present at a line level.
(Required in AU & NZ)
<InvoiceDetailLineIndicator isTaxInLine="yes"/>
The InvoicePartner element contains the Bill To contact.
<InvoicePartner>
<Contact role="billTo">
<Name lang="en">Bill To Address</Name>
<PostalAddress>
<Street>123 Something Street</Street>
<City>Auckland</City>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
</Contact>
</InvoicePartner>
This will show for the customer in the Bill To section on the Invoice in Unimarket
InvoiceDetailOrder
This contains the InvoiceDetailOrderInfo element which provides a reference to the matching purchase order.
<InvoiceDetailOrderInfo>
<OrderReference orderID="[Purchase Order Number]"/>
</InvoiceDetailOrderInfo>
InvoiceDetailOrder will contain one or more InvoiceDetailItem elements.
These contain more information about the lines listed on the invoice.
Example InvoiceDetailItem
<InvoiceDetailItem invoiceLineNumber="2" quantity="12.00">
<InvoiceDetailItemReference lineNumber="2">
<ItemID>
<SupplierPartID>2223414</SupplierPartID>
</ItemID>
<Description lang="en">TISSUE FACIAL TORK 2311408 PREMIUM 2 PLY PK/100</Description>
</InvoiceDetailItemReference>
<UnitOfMeasure>PACK</UnitOfMeasure>
<UnitPrice>
<Money currency="NZD">1.09</Money>
</UnitPrice>
<SubtotalAmount>
<Money currency="NZD">13.08</Money>
</SubtotalAmount>
<Tax>
<Money currency="NZD">1.962</Money>
<Description lang="en">GST</Description>
</Tax>
</InvoiceDetailItem>
InvoiceDetailItem
The invoiceLineNumber attribute is the Invoice Line Number.
The quantity attribute is the quantity for the Invoice Line being invoiced.
<InvoiceDetailItem invoiceLineNumber="2" quantity="12.00">
InvoiceDetailItemReference
The InvoiceDetailItemReference contains the lineNumber attribute, this is the reference that matches up the Invoice Line with the Purchase Order Line.
The ItemID element contains the SupplierPartID element which is the product code for the line.
The Description element contains the description for the line.
<InvoiceDetailItemReference lineNumber="2">
<ItemID>
<SupplierPartID>2223414</SupplierPartID>
</ItemID>
<Description lang="en">TISSUE FACIAL TORK 2311408 PREMIUM 2 PLY PK/100</Description>
</InvoiceDetailItemReference>
UnitOfMeasure
The UnitOfMeasure element contains the Unit Of Measure (UOM) the line was invoiced in.
This must match the UOM for the purchase order line.
<UnitOfMeasure>PACK</UnitOfMeasure>
UnitPrice
The UnitPrice element contains the Money element.
The Money element has a currency attribute and the per unit price for the line.
<UnitPrice>
<Money currency="NZD">1.09</Money>
</UnitPrice>
Subtotal
The Subtotal element contains the Money element.
The Money element has a currency attribute and the subtotal for the line.
This should be calculated based on UnitPrice x Quantity = Subtotal
In this example it would be: 1.09 x 12 = 13.08
<SubtotalAmount>
<Money currency="NZD">13.08</Money>
</SubtotalAmount>
Tax
The Tax element contains the Money and Description elements.
The Money element has a currency attribute and tax amount for the line.
This should be calculated based on Subtotal x Tax Rate = Tax
In this example it would be: 13.08 x 0.15 (15%) = 1.962
The Description element contains the name of this type of tax. In this example it would be GST.
<Tax>
<Money currency="NZD">1.962</Money>
<Description lang="en">GST</Description>
</Tax>
InvoiceDetailSummary
The InvoiceDetailSummary element contains totals used validate the invoice.
| Note: Unimarket will calculate the totals of each line and check these match with what is provided in the InvoiceDetailSummary. Any differences will cause the invoice to fail validation. |
Example InvoiceDetailSummary
<InvoiceDetailSummary>
<SubtotalAmount>
<Money currency="NZD">40.53</Money>
</SubtotalAmount>
<Tax>
<Money currency="NZD">6.0795</Money>
<Description lang="en">GST</Description>
</Tax>
<GrossAmount>
<Money currency="NZD">46.6095</Money>
</GrossAmount>
</InvoiceDetailSummary>
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.
<SubtotalAmount>
<Money currency="NZD">40.53</Money>
</SubtotalAmount>
This should be calculated based on the sum of the subtotal amounts from each line.
In this example it would be: 17.05 + 13.08 + 10.40 = 40.53
<InvoiceDetailItem invoiceLineNumber="1" quantity="1.00">
<SubtotalAmount>
<Money currency="NZD">17.05</Money>
</SubtotalAmount>
</InvoiceDetailItem>
<InvoiceDetailItem invoiceLineNumber="2" quantity="12.00">
<SubtotalAmount>
<Money currency="NZD">13.08</Money>
</SubtotalAmount>
</InvoiceDetailItem>
<InvoiceDetailItem invoiceLineNumber="3" quantity="10.00">
<SubtotalAmount>
<Money currency="NZD">10.40</Money>
</SubtotalAmount>
</InvoiceDetailItem>
Tax
The Tax element contains the Money element.
The Money element has a currency attribute and the sum total of tax for all lines on the invoice.
The Description element contains the name of this type of tax. In this example it would be GST.
<Tax>
<Money currency="NZD">6.0795</Money>
<Description lang="en">GST</Description>
</Tax>
This should be calculated based on the sum of the tax amounts from each line.
In this example it would be: 2.5575 + 1.962 + 1.56 = 6.0795
<InvoiceDetailItem invoiceLineNumber="1" quantity="1.00">
<Tax>
<Money currency="NZD">2.5575</Money>
<Description lang="en">GST</Description>
</Tax>
</InvoiceDetailItem>
<InvoiceDetailItem invoiceLineNumber="2" quantity="12.00">
<Tax>
<Money currency="NZD">1.962</Money>
<Description lang="en">GST</Description>
</Tax>
</InvoiceDetailItem>
<InvoiceDetailItem invoiceLineNumber="3" quantity="10.00">
<Tax>
<Money currency="NZD">1.56</Money>
<Description lang="en">GST</Description>
</Tax>
</InvoiceDetailItem>
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 + Tax = GrossAmount
In this example it would be: 40.53 + 6.0795 = 46.6095
<GrossAmount>
<Money currency="NZD">46.6095</Money>
</GrossAmount>
Complete Basic Invoice Example
<cXML payloadID="[A Unique Value]" timestamp="2020-10-08T23:59:45-07:00" version="1.2.021">
<Header>
<From>
<Credential domain="unimarket-id">
<Identity>82d1aa66-095a-45a8-b8f1-20778aac4ed8</Identity>
</Credential>
</From>
<To>
<Credential domain="unimarket-code">
<Identity>miketest</Identity>
</Credential>
</To>
<Sender>
<Credential domain="unimarket-user">
<Identity>fd36b3b9-ad5a-4fa6-aedd-a826b7b3d87b</Identity>
<SharedSecret>Super Secret Password</SharedSecret>
</Credential>
<UserAgent>Suppliers Software System</UserAgent>
</Sender>
</Header>
<Request deploymentMode="test">
<InvoiceDetailRequest>
<InvoiceDetailRequestHeader invoiceDate="2020-10-08" invoiceID="TestInvoice10018" operation="new" purpose="standard">
<InvoiceDetailLineIndicator isTaxInLine="yes"/>
<InvoicePartner>
<Contact role="billTo">
<Name lang="en">Bill To Address</Name>
<PostalAddress>
<Street>123 Something Street</Street>
<City>Auckland</City>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
</Contact>
</InvoicePartner>
</InvoiceDetailRequestHeader>
<InvoiceDetailOrder>
<InvoiceDetailOrderInfo>
<OrderReference orderID="[Purchase Order Number]"/>
</InvoiceDetailOrderInfo>
<InvoiceDetailItem invoiceLineNumber="1" quantity="1.00">
<InvoiceDetailItemReference lineNumber="1">
<ItemID>
<SupplierPartID>1497243</SupplierPartID>
</ItemID>
<Description lang="en">LAMINATING POUCH A4 80MU GLOSSY FINISH PK/100</Description>
</InvoiceDetailItemReference>
<UnitOfMeasure>PACK</UnitOfMeasure>
<UnitPrice>
<Money currency="NZD">17.05</Money>
</UnitPrice>
<SubtotalAmount>
<Money currency="NZD">17.05</Money>
</SubtotalAmount>
<Tax>
<Money currency="NZD">2.5575</Money>
<Description lang="en">GST</Description>
</Tax>
</InvoiceDetailItem>
<InvoiceDetailItem invoiceLineNumber="2" quantity="12.00">
<InvoiceDetailItemReference lineNumber="2">
<ItemID>
<SupplierPartID>2223414</SupplierPartID>
</ItemID>
<Description lang="en">TISSUE FACIAL TORK 2311408 PREMIUM 2 PLY PK/100</Description>
</InvoiceDetailItemReference>
<UnitOfMeasure>PACK</UnitOfMeasure>
<UnitPrice>
<Money currency="NZD">1.09</Money>
</UnitPrice>
<SubtotalAmount>
<Money currency="NZD">13.08</Money>
</SubtotalAmount>
<Tax>
<Money currency="NZD">1.962</Money>
<Description lang="en">GST</Description>
</Tax>
</InvoiceDetailItem>
<InvoiceDetailItem invoiceLineNumber="3" quantity="10.00">
<InvoiceDetailItemReference lineNumber="3">
<ItemID>
<SupplierPartID>1046543</SupplierPartID>
</ItemID>
<Description lang="en">FINGER CONE NO 0 </Description>
</InvoiceDetailItemReference>
<UnitOfMeasure>EACH</UnitOfMeasure>
<UnitPrice>
<Money currency="NZD">1.04</Money>
</UnitPrice>
<SubtotalAmount>
<Money currency="NZD">10.40</Money>
</SubtotalAmount>
<Tax>
<Money currency="NZD">1.56</Money>
<Description lang="en">GST</Description>
</Tax>
</InvoiceDetailItem>
</InvoiceDetailOrder>
<InvoiceDetailSummary>
<SubtotalAmount>
<Money currency="NZD">40.53</Money>
</SubtotalAmount>
<Tax>
<Money currency="NZD">6.0795</Money>
<Description lang="en">GST</Description>
</Tax>
<GrossAmount>
<Money currency="NZD">46.6095</Money>
</GrossAmount>
</InvoiceDetailSummary>
</InvoiceDetailRequest>
</Request>
</cXML>
When looking at this invoice in the Unimarket Supplier Store the cXML invoice will be a downloadable attachment called invoice.xml
Invoice Accepted Response
This is an example of the response you will receive when an Invoice is accepted.
<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="1602730925188" timestamp="2020-10-15T16:02:05.188+13:00" version="1.2.021" xml:lang="en">
<Response>
<Status code="201" text="Invoice Message Accepted"/>
</Response>
</cXML>
Shipping at Header Level
A Shipping charge can be applied to the Invoice at the header level.
This requires new elements in the InvoiceDetailRequestHeader element, the InvoiceDetailSummary element and some changes to the calculations in the Tax and GrossAmount elements in the InvoiceDetailSummary.
InvoiceDetailShipping
The InvoiceDetailShipping element needs to be included in the InvoiceDetailRequestHeader element.
This contains the shipTo Contact which is where the goods were shipped to. Note: If the InvoiceDetailShipping element is omitted, Unimarket will not import any shipping charges from the invoice, but the invoice will not generate an error response from our server.
<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>
This will show for the customer in the Ship To section on the Invoice in Unimarket.
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 Shipping Amount without tax for the invoice.
In this example it would be: 10.00
<ShippingAmount>
<Money currency="NZD">10.00</Money>
</ShippingAmount>
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 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") and the Tax on Shipping (purpose="shippingTax").
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: 10.00 x 0.15 (15%) = 1.50
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">10.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">1.50</Money>
</TaxAmount>
<Description lang="en">GST</Description>
</TaxDetail>
In this example it would be: 6.0795 (Tax on Goods) + 1.50 (Tax on Shipping) = 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>
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 + Tax = GrossAmount
In this example it would be: 40.53 + 10.00 + 7.5795 = 58.1095
<GrossAmount>
<Money currency="NZD">58.1095</Money>
</GrossAmount>
InvoiceDetailSummary
Below is the example InvoiceDetailSummary section including shipping.
<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>
When looking at this invoice in the Unimarket Supplier Store the cXML invoice will be a downloadable attachment called invoice.xml
Shipping at Line Level
A Shipping 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 isShippingInLine attribute and be set to "yes".
<InvoiceDetailRequestHeader invoiceDate="2020-10-08" invoiceID="TestInvoice10020" operation="new" purpose="standard">
<InvoiceDetailLineIndicator isTaxInLine="yes" isShippingInLine="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.
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>
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 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") and the Tax on Shipping (purpose="shippingTax").
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>
In this example it would be: 6.0795 (Tax on Goods) + 2.25 (Tax on Shipping) = 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>
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 + Tax = GrossAmount
In this example it would be: 40.53 + 15.00 + 8.3295 = 63.8595
<GrossAmount>
<Money currency="NZD">63.8595</Money>
</GrossAmount>
InvoiceDetailSummary
Below is the example InvoiceDetailSummary section including shipping.
<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>
When looking at this invoice in the Unimarket Supplier Store the cXML invoice will be a downloadable attachment called invoice.xml
Shipping and Special Handling at Header Level
A Shipping charge and a Special Handling charge can be applied to the Invoice at the header level.
This requires new elements in the InvoiceDetailRequestHeader element, the InvoiceDetailSummary element and some changes to the calculations in the Tax and GrossAmount elements in the InvoiceDetailSummary.
InvoiceDetailShipping
The InvoiceDetailShipping element needs to be included in the InvoiceDetailRequestHeader element.
This contains the shipTo Contact which is where the goods were shipped to.
<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>
This will show for the customer in the Ship To section on the Invoice in Unimarket.
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 Shipping Amount without tax for the invoice.
In this example it would be: 10.00
<ShippingAmount>
<Money currency="NZD">10.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 Special Handling Amount without tax for the invoice.
In this example it would be: 25.00
<SpecialHandlingAmount>
<Money currency="NZD">25.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: 10.00 x 0.15 (15%) = 1.50
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">10.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">1.50</Money>
</TaxAmount>
<Description lang="en">GST</Description>
</TaxDetail>
Special Handling:
In this example it would be: 25.00 x 0.15 (15%) = 3.75
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">25.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">3.75</Money>
</TaxAmount>
<Description lang="en">GST</Description>
</TaxDetail>
In this example it would be:
6.0795 (Tax on Goods) + 1.50 (Tax on Shipping) + 3.75 (Tax on Special Handling) = 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>
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 + 25.00 + 11.3295 = 86.8595
<GrossAmount>
<Money currency="NZD">86.8595</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">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>
When looking at this invoice in the Unimarket Supplier Store the cXML invoice will be a downloadable attachment called invoice.xml
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>
When looking at this invoice in the Unimarket Supplier Store the cXML invoice will be a downloadable attachment called invoice.xml
Additional Information