Invoices
-
Invoice Integration - 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.
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>See the articles below for additional information on Invoice Integration:
Invoice Integration - cXML Request
Invoice Integration - cXML Header (Credentials)
Invoice Integration - InvoiceDetailSummary
Invoice Integration - InvoiceDetailOrder
Invoice Integration - Discount at Header Level
Invoice Integration - Shipping at Header Level
Invoice Integration - Shipping at Line Level
Invoice Integration - Shipping & Special Handling at Header Level
Invoice Integration - Shipping & Special Handling at Line Level
-
Invoice Integration - cXML Request
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.
See the articles below for additional information on Invoice Integration:
Invoice Integration - Overview
Invoice Integration - cXML Header (Credentials)
Invoice Integration - InvoiceDetailSummary
Invoice Integration - InvoiceDetailOrder
Invoice Integration - Discount at Header Level
Invoice Integration - Shipping at Header Level
Invoice Integration - Shipping at Line Level
Invoice Integration - Shipping & Special Handling at Header Level
Invoice Integration - Shipping & Special Handling at Line Level
-
Invoice Integration - 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.
See the articles below for additional information on Invoice Integration:
Invoice Integration - Overview
Invoice Integration - cXML Request
Invoice Integration - InvoiceDetailSummary
Invoice Integration - InvoiceDetailOrder
Invoice Integration - Discount at Header Level
Invoice Integration - Shipping at Header Level
Invoice Integration - Shipping at Line Level
Invoice Integration - Shipping & Special Handling at Header Level
Invoice Integration - Shipping & Special Handling at Line Level
-
Invoice Integration - InvoiceDetailSummary
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
See the articles below for additional information on Invoice Integration:
Invoice Integration - Overview
Invoice Integration - cXML Request
Invoice Integration - cXML Header (Credentials)
Invoice Integration - InvoiceDetailOrder
Invoice Integration - Discount at Header Level
Invoice Integration - Shipping at Header Level
Invoice Integration - Shipping at Line Level
Invoice Integration - Shipping & Special Handling at Header Level
Invoice Integration - Shipping & Special Handling at Line Level
Invoice Integration - Invoice Accepted Response
Troubleshooting Integrated Invoices
-
Invoice Integration - InvoiceDetailOrder
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>See the articles below for additional information on Invoice Integration:
Invoice Integration - Overview
Invoice Integration - cXML Request
Invoice Integration - cXML Header (Credentials)
Invoice Integration - InvoiceDetailSummary
Invoice Integration - Discount at Header Level
Invoice Integration - Shipping at Header Level
Invoice Integration - Shipping at Line Level
Invoice Integration - Shipping & Special Handling at Header Level
Invoice Integration - Shipping & Special Handling at Line Level
-
Invoice Integration - Discount at Header Level
Discount at Header Level
A Discount 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.
Sample Discount Format
<InvoiceDetailDiscount percentageRate="10.00">
<Money currency="USD">22.50</Money>
</InvoiceDetailDiscount>Net Amount & Due Amount
The NetAmount &DueAmount elements both contain the Money element.
This should be calculated based on Subtotal + ShippingAmount + Tax = GrossAmount - Discount = Net Amount/Amount Due
In this example it would be: 200.00 + 10.00 + 15.00 = 225.00 - 22.50 = 202.50
<NetAmount>
<Money currency="USD">202.5</Money>
</NetAmount>
<DueAmount>
<Money currency="USD">202.5</Money>
</DueAmount>InvoiceDetailSummary
Below is the example InvoiceDetailSummary section including discount.
<InvoiceDetailSummary>
<SubtotalAmount>
<Money currency="USD">200.00</Money>
</SubtotalAmount>
<Tax>
<Money currency="USD">15.00</Money>
<Description xml:lang="en-US">Cost of tax, including shipping tax</Description>
<TaxDetail category="sales" percentageRate="7.5" purpose="tax">
<TaxableAmount>
<Money currency="USD">200.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="USD">15.00</Money>
</TaxAmount>
</TaxDetail>
</Tax>
<SpecialHandlingAmount>
<Money currency="USD">0.00</Money>
<Description xml:lang="en-US">Other Charges</Description>
</SpecialHandlingAmount>
<ShippingAmount>
<Money currency="USD">10.00</Money>
</ShippingAmount>
<GrossAmount>
<Money currency="USD">225.00</Money>
</GrossAmount>
<InvoiceDetailDiscount percentageRate="10.00">
<Money currency="USD">22.50</Money>
</InvoiceDetailDiscount>
<NetAmount>
<Money currency="USD">202.5</Money>
</NetAmount>
<DueAmount>
<Money currency="USD">202.5</Money>
</DueAmount>
</InvoiceDetailSummary>See the articles below for additional information on Invoice Integration:
Invoice Integration - Overview
Invoice Integration - cXML Request
Invoice Integration - cXML Header (Credentials)
Invoice Integration - InvoiceDetailSummary
Invoice Integration - InvoiceDetailOrder
Invoice Integration - Shipping at Header Level
Invoice Integration - Shipping at Line Level
Invoice Integration - Shipping & Special Handling at Header Level
Invoice Integration - Shipping & Special Handling at Line Level
-
Invoice Integration - Payment Terms
Payment Terms
The cXML standard outlines the payment term information as follows.
- payInNumberOfDays - Indicates the invoice must be paid in a certain number of days after the invoice effective date.
- Discount - The percentage or amount of the discount term. The discount rate applies if the invoice total is paid within the time specified by payInNumberOfDays.
- Discount percent - a percent number
- Discount due days - a number of days. If payment is made before this, the discount percent applies.
- Extrinsic - can be used to capture things like a due date (you can insert the current Payment Date in here)
Example of PaymentTerms
<PaymentTerm payInNumberOfDays="45">
</PaymentTerm>
<PaymentTerm payInNumberOfDays="30">
<Discount>
<DiscountPercent percent="2">
</Discount>
</PaymentTerm>
<PaymentTerm payInNumberOfDays="20">
<Discount>
<DiscountPercent percent="3">
</Discount>
</PaymentTerm>Payment Terms display the code in the payInNumberOfDays field and adding an Extrinsic (NetDueDays) to show the actual Net Days.
Unimarket Recommended cXML
<PaymentTerm payInNumberOfDays='30'>
<Discount>
<DiscountPercent percent='2' />
<DiscountDueDays>10</DiscountDueDays>
</Discount>
<Extrinsic name='PaymentCode'>Net30Discount10</Extrinsic>
</PaymentTerm> -
Invoice Integration - Shipping at Header Level
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
See the articles below for additional information on Invoice Integration:
Invoice Integration - Overview
Invoice Integration - cXML Request
Invoice Integration - cXML Header (Credentials)
Invoice Integration - InvoiceDetailSummary
Invoice Integration - InvoiceDetailOrder
Invoice Integration - Discount at Header Level
Invoice Integration - Shipping at Line Level
Invoice Integration - Shipping & Special Handling at Header Level
Invoice Integration - Shipping & Special Handling at Line Level
Invoice Integration - Invoice Accepted Response
Troubleshooting Integrated Invoices
-
Invoice Integration - Shipping at Line Level
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
See the articles below for additional information on Invoice Integration:
Invoice Integration - Overview
Invoice Integration - cXML Request
Invoice Integration - cXML Header (Credentials)
Invoice Integration - InvoiceDetailSummary
Invoice Integration - InvoiceDetailOrder
Invoice Integration - Discount at Header Level
Invoice Integration - Shipping at Header Level
Invoice Integration - Shipping & Special Handling at Header Level
Invoice Integration - Shipping & Special Handling at Line Level
-
Invoice Integration - Shipping & Special Handling at Header Level
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
See the articles below for additional information on Invoice Integration:
Invoice Integration - Overview
Invoice Integration - cXML Request
Invoice Integration - cXML Header (Credentials)
Invoice Integration - InvoiceDetailSummary
Invoice Integration - InvoiceDetailOrder
Invoice Integration - Discount at Header Level
Invoice Integration - Shipping at Header Level
Invoice Integration - Shipping at Line Level
Invoice Integration - Shipping & Special Handling at Line Level
Invoice Integration - Invoice Accepted Response
Troubleshooting Integrated Invoices
-
Invoice Integration - Shipping & Special Handling at Line Level
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
See the articles below for additional information on Invoice Integration:
Invoice Integration - Overview
Invoice Integration - cXML Request
Invoice Integration - cXML Header (Credentials)
Invoice Integration - InvoiceDetailSummary
Invoice Integration - InvoiceDetailOrder
Invoice Integration - Discount at Header Level
Invoice Integration - Shipping at Header Level
Invoice Integration - Shipping at Line Level
Invoice Integration - Shipping & Special Handling at Header Level
Invoice Integration - Invoice Accepted Response
Troubleshooting Integrated Invoices
-
Invoice Integration - Invoice Accepted Response
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>See the articles below for additional information on Invoice Integration:
Invoice Integration - Overview
Invoice Integration - cXML Request
Invoice Integration - cXML Header (Credentials)
Invoice Integration - InvoiceDetailSummary
Invoice Integration - InvoiceDetailOrder
Invoice Integration - Discount at Header Level
Invoice Integration - Shipping at Header Level
Invoice Integration - Shipping at Line Level
Invoice Integration - Shipping & Special Handling at Header Level
Invoice Integration - Shipping & Special Handling at Line Level
-
Credit Note Integration
A Credit Note in Unimarket is treated as a negative invoice. This means it will use the same structure as an invoice however with a negative quantity and negative totals, The unit price remains positive.
Note: Credits must only contain negative lines. They cannot have a mix of negative and positive lines. Example InvoiceDetailOrder
<InvoiceDetailOrder>
<InvoiceDetailOrderInfo>
<OrderReference orderID="684078"/>
</InvoiceDetailOrderInfo>
<InvoiceDetailItem invoiceLineNumber="2" quantity="-1.00">
<UnitOfMeasure>PACK</UnitOfMeasure>
<UnitPrice>
<Money currency="NZD">11.80</Money>
</UnitPrice>
<InvoiceDetailItemReference lineNumber="2">
<ItemID>
<SupplierPartID>PROD12345</SupplierPartID>
</ItemID>
<Description lang="en">Example Product Description</Description>
</InvoiceDetailItemReference>
<SubtotalAmount>
<Money currency="NZD">-11.80</Money>
</SubtotalAmount>
<Tax>
<Money currency="NZD">-1.77</Money>
<Description lang="en">GST</Description>
</Tax>
</InvoiceDetailItem>
</InvoiceDetailOrder>Subtotal Calculation
Quantity: -1.00
<InvoiceDetailItem invoiceLineNumber="2" quantity="-1.00">
Unit Price: 11.80
<UnitPrice><Money currency="NZD">11.80</Money></UnitPrice>
Quantity x Unit Price = Subtotal
-1.00 x 11.80 = -11.80
<SubtotalAmount><Money currency="NZD">-11.80</Money></SubtotalAmount>
Example InvoiceDetailSummary
<InvoiceDetailSummary>
<SubtotalAmount>
<Money currency="NZD">-11.80</Money>
</SubtotalAmount>
<Tax>
<Money currency="NZD">-1.77</Money>
<Description lang="en">GST</Description>
</Tax>
<GrossAmount>
<Money currency="NZD">-13.57</Money>
</GrossAmount>
<NetAmount>
<Money currency="NZD">-13.57</Money>
</NetAmount>
</InvoiceDetailSummary>See the articles below for additional information on Invoice Integration:
Invoice Integration - Overview
Invoice Integration - cXML Request
Invoice Integration - cXML Header (Credentials)
Invoice Integration - InvoiceDetailSummary
Invoice Integration - InvoiceDetailOrder
Invoice Integration - Discount at Header Level
Invoice Integration - Shipping at Header Level
Invoice Integration - Shipping at Line Level
Invoice Integration - Shipping & Special Handling at Header Level
Invoice Integration - Shipping & Special Handling at Line Level
-
Troubleshooting Integrated Invoices
When an integrated invoice is sent to Unimarket the document is validated to ensure that all the required elements are included, the summary totals match the calculated totals of the lines, there is a matching purchase order and matching lines. Providing this validation step is successful the invoice will be processed based on the customers settings. If the validation fails then an error response is sent back.
Below are some examples of errors you might receive when an invoice fails validation and suggested solutions on how to fix them.
INVOICE integration is not enabled
Failed to authenticate for CXML message: The site or user credentials are invalid
Invalid credentials. Problems were: [CommunitySite with DUNS [XXXXX] does not exist]
Invalid credentials. Problems were: [CommunitySite with UUID [XXXXX] does not exist]
Invalid credentials. Problems were: [CommunitySite with code [XXXXX] does not exist]
Invalid credentials. Problems were: []
Invoice Detail must have an order id
No order exists in [Customer] for [Supplier] with the order number: 'XXXXX'
An invoice with invoice number 'XXXXX' has already been processed
'null' is not a valid long (InvoiceDetailItem/lineNumber)
InvoiceDetailRequestHeader/invoiceDate: Could not parse XXXXX
Each line does not have a 'InvoiceDetailItemReference/ItemID/SupplierPartID' element
'InvoiceDetailLineIndicator/@isTaxInLine' is set to '' but some lines have a 'Tax' element
'InvoiceDetailOrder/InvoiceDetailItem/UnitPrice/Money' must be a number
The supplied value (XXX) does not have the same currency (XXX) as this
The order with the order number: 'XXXXX' cannot be invoiced at this time
Invalid Unit Of Measure [XXXXX] on line [X] of Invoice [XXXXX]
Could not find order item in order 'XXXXX' at line 'X'
Could not find order item in order 'XXXXX' with the sku 'XXXXX'
Subtotal in summary (XXX XXX.XX), does not match subtotal of lines (XXX XXX.XX)
Tax in summary (XXX XXX.XX), does not match tax of lines (XXX XXX.XX)
Gross amount (XXX XXX.XX) should be subtotal + tax + shipping + special handling (XXX XXX.XX)
Invoice Message Accepted
<Status code="201" text="Invoice Message Accepted"/>
This shows that the invoice has passed validation, matches successfully with a purchase order and lines.
Solution
No further action is required.
INVOICE integration is not enabled
<Status code="400" text="INVOICE integration is not enabled."/>
The inbound integration has not been enabled for your supplier store. This needs to be enabled before any invoices will be processed.
Solution
Contact Unimarket Support via support@unimarket.com to request this be enabled for your supplier store.
Failed to authenticate for CXML message: The site or user credentials are invalid
<Status code="401" text="Failed to authenticate for CXML message: The site or user credentials are invalid."/>
The credentials supplied in the cXML header are invalid.
Solution
Contact Unimarket Support via support@unimarket.com to confirm the credentials for the cXML Header From, To and Sender elements. Please include the customer this relates to. cXML Header Credentials are explained here: cXML Header (Credentials).
Invalid credentials. Problems were: [CommunitySite with DUNS [XXXXX] does not exist]
<Status code="400" text="Invalid credentials. Problems were: [CommunitySite with DUNS [XXXXX] does not exist]"/>
The DUNS identifier in the cXML header To element does not match with any customers.
Solution
Contact Unimarket Support via support@unimarket.com to confirm the credentials for the cXML Header To element. Please include the customer this relates to. cXML Header Credentials are explained here: cXML Header (Credentials).
Invalid credentials. Problems were: [CommunitySite with UUID [XXXXX] does not exist]
<Status code="400" text="Invalid credentials. Problems were: [CommunitySite with UUID [XXXXX] does not exist]"/>
The unimarket-id identifier in the cXML header To element does not match with any customers.
Solution
Contact Unimarket Support via support@unimarket.com to confirm the credentials for the cXML Header To element. Please include the customer this relates to. cXML Header Credentials are explained here: cXML Header (Credentials).
Invalid credentials. Problems were: [CommunitySite with code [XXXXX] does not exist]
<Status code="400" text="Invalid credentials. Problems were: [CommunitySite with code [XXXXX] does not exist]"/>
The unimarket-code identifier in the cXML header To element does not match with any customers.
Solution
Contact Unimarket Support via support@unimarket.com to confirm the credentials for the cXML Header To element. Please include the customer this relates to. cXML Header Credentials are explained here: cXML Header (Credentials).
Invalid credentials. Problems were: []
<Status code="400" text="Invalid credentials. Problems were: []"/>
The credentials supplied in the cXML header are invalid. This is typically caused by an invalid cXML Header credential domain being used like "NetworkID".
Solution
Ensure you are sending a valid cXML Header Domain as explained here: cXML Header (Credentials)
Country code must not be blank cxmlPostalAddress=CXMLPostalAddress: name=null, deliverTo=null, street1=XXXXX, street2=null, street3=null, city=XXXXX, state=null, postcode=XXXXX, countryName=XXXXX, countryCode=null"
<Status code="400" text="Country code must not be blank cxmlPostalAddress=CXMLPostalAddress: name=null, deliverTo=null, street1=XXXXX, street2=null, street3=null, city=XXXXX, state=null, postcode=XXXXX, countryName=XXXXX, countryCode=null"/>
The billTo Contact must have a valid isoCountryCode attribute that is not null.
Solution
Ensure you are sending a valid isoCountryCode attribute in the billTo Contact as shown in the example here: cXML Request
Invoice Detail must have an order id
<Status code="400" text="Invoice Detail must have an order id"/>
The InvoiceDetailOrderInfo element is missing from the InvoiceDetailOrder element. This includes the OrderReference element which matches this invoice to the purchase order.
Solution
Ensure you are sending the InvoiceDetailOrderInfo element as explained here: InvoiceDetailOrder
No order exists in [Customer] for [Supplier] with the order number: 'XXXXX'
<Status code="400" text="No order exists in [Customer] for [Supplier] with the order number: 'XXXXX'"/>
The orderID provided in the invoice did not match a purchase order raised by the customer with the supplier.
Solution
Contact the customer to ensure the purchase order number is a valid Unimarket purchase order number.
An invoice with invoice number 'XXXXX' has already been processed
<Status code="400" text="An invoice with invoice number 'XXXXX' has already been processed"/>
The invoice number has already been processed for the customer and supplier.
Solution
If the original invoice has not been matched or has been rejected you may be able to cancel the invoice. To do this log into the supplier portal, search for the invoice and select the invoice number. When viewing the invoice, in the top right hand corner click More Actions and select Cancel, provide a reason and click OK. You can now re-send this invoice.
If the original invoice has been accepted or downloaded then invoices with the same number will be rejected as duplicates. Please use a unique invoice number.
'null' is not a valid long (InvoiceDetailItem/lineNumber)
<Status code="400" text="'null' is not a valid long (InvoiceDetailItem/lineNumber)"/>
The lineNumber attribute is not found or contains an invalid number.
Solution
Ensure you are sending the lineNumber Attribute as explained here: InvoiceDetailItemReference
InvoiceDetailRequestHeader/invoiceDate: Could not parse XXXXX
<Status code="400" text="InvoiceDetailRequestHeader/invoiceDate: Could not parse XXXXX"/>
The invoiceDate attribute is not a valid date.
Solution
Ensure you are sending the invoiceDate attribute as explained here: InvoiceDetailRequestHeader
Each line does not have a 'InvoiceDetailItemReference/ItemID/SupplierPartID' element
<Status code="400" text="Each line does not have a 'InvoiceDetailItemReference/ItemID/SupplierPartID' element"/>
The SupplierPartID element is not found in every line.
Solution
Ensure you are sending all the required elements of the InvoiceDetailItem as explained here: InvoiceDetailItem
Argument for @NotNull parameter 'unitOfMeasure' of com/unimarket/invoicing/domain/InvoiceLineItemImpl.<init> must not be null
<Status code="400" text="Argument for @NotNull parameter 'unitOfMeasure' of com/unimarket/invoicing/domain/InvoiceLineItemImpl.<init> must not be null"/>
The unitOfMeasure element is not found in every line.
Solution
Ensure you are sending all the required elements of the InvoiceDetailItem as explained here: InvoiceDetailItem
Unit Of Measure [XX] on line [X] of Invoice [XXXXXX] does not match the one on the corresponding Order line [XX]
<Status code="400" text="Unit Of Measure [XX] on line [X] of Invoice [XXXXXX] does not match the one on the corresponding Order line [XX]"/>
The Unit Of Measure provided on the invoice does not match the Unit Of Measure for the Order line.
Solution
Ensure you are sending the correct Unit Of Measure as shown on the Order. To avoid this in the future you may want to update your catalogue to ensure the current Unit Of Measure is available.
'InvoiceDetailLineIndicator/@isTaxInLine' is set to '' but some lines have a 'Tax' element
<Status code="400" text="'InvoiceDetailLineIndicator/@isTaxInLine' is set to '' but some lines have a 'Tax' element"/>
Tax elements have been found at the line level in the InvoiceDetailItem element however the isTaxInLine attribute has not been set in the InvoiceDetailLineIndicator element.
Solution
Ensure you are sending all the required elements of the InvoiceDetailRequestHeader as explained here: InvoiceDetailRequestHeader
'InvoiceDetailOrder/InvoiceDetailItem/UnitPrice/Money' must be a number
<Status code="400" text="'InvoiceDetailOrder/InvoiceDetailItem/UnitPrice/Money' must be a number."/>
The Money element is not found or contains an invalid number.
Solution
The UnitPrice/Money element must not contain any special characters. Only numbers and a single decimal character. Do not use a thousand separator. The UnitPrice element is explained here: UnitPrice
The supplied value (XXX) does not have the same currency (XXX) as this
<Status code="400" text="The supplied value (XXX) does not have the same currency (XXX) as this"/>
The currency attribute of a Money element is different to other currency attributes.
Solution
Ensure you are sending a consistent currency for all lines and summary totals in the invoice.
This money instance [XXX XXXXX.XX] does not have the same currency as the supplied instance [XXX XXXXX.XX]
<Status code="400" text="This money instance [XXX XXXXX.XX] does not have the same currency as the supplied instance [XXX XXXXX.XX]"/>
The invoice contains a different currency to the purchase order currency.
Solution
Contact your customer to ensure you have raised the invoice in the expected currency.
The order with the order number: 'XXXXX' cannot be invoiced at this time
<Status code="400" text="The order with the order number: 'XXXXX' cannot be invoiced at this time"/>
The purchase order number that is referenced in the invoice has been closed. This means no actions can be processed against it, including: editing, cancelling or receiving lines on the order as well as Invoices and Credits will no longer be accepted.
Purchase orders that have been paid via Credit Card or Stripe will be automatically closed and any invoice raised against those orders will be rejected for the same reason.
Solution
Contact your customer to understand why the order is now closed. If the customer re-opens the order then you can re-send this invoice.
Invalid Unit Of Measure [XXXXX] on line [X] of Invoice [XXXXX]
<Status code="400" text="Invalid Unit Of Measure [XXXXX] on line [X] of Invoice [XXXXX]"/>
The UnitOfMeasure provided on the invoice line does not match the Unit Of Measure for the purchase order line.
Solution
Ensure you are sending the correct UnitOfMeasure value that matches what was on the purchase order line as explained here: UnitOfMeasure
Could not find order item in order 'XXXXX' at line 'X'
<Status code="400" text="Could not find order item in order 'XXXXX' at line 'X'"/>
Unimarket couldn't match an invoice line to the purchase order line based on the line number.
Solution
Ensure you are only invoicing lines that appear on the purchase order. Contact your customer to discuss how to invoice for lines that are in addition to the original purchase order lines. This might require an additional purchase order to be generated.
Could not find order item in order 'XXXXX' with the sku 'XXXXX'
<Status code="400" text="Could not find order item in order 'XXXXX' with the sku 'XXXXX'"/>
Unimarket couldn't match an invoice line to the purchase order line based on the SupplierPartID.
Solution
Ensure you are only invoicing lines that appear on the purchase order. Contact your customer to discuss how to invoice for lines that are in addition to the original purchase order lines. This might require an additional purchase order to be generated.
Subtotal in summary (XXX XXX.XX), does not match subtotal of lines (XXX XXX.XX)
<Status code="400" text="Subtotal in summary (XXX XXX.XX), does not match subtotal of lines (XXX XXX.XX)"/>
The calculated sum of the subtotal for each line does not match the SubtotalAmount in the InvoiceDetailSummary.
Solution
Ensure the SubtotalAmount is the calculated sum of the subtotal for each line as explained here: SubtotalAmount
Tax in summary (XXX XXX.XX), does not match tax of lines (XXX XXX.XX)
<Status code="400" text="Tax in summary (XXX XXX.XX), does not match tax of lines (XXX XXX.XX)"/>
The calculated sum of the tax for each line does not match the Tax in the InvoiceDetailSummary.
Solution
Ensure the Tax is the calculated sum of the tax for each line as explained here: Summary Tax
Gross amount (XXX XXX.XX) should be subtotal + tax + shipping + special handling (XXX XXX.XX)
<Status code="400" text="Gross amount (XXX XXX.XX) should be subtotal + tax + shipping + special handling (XXX XXX.XX)"/>
The calculated sum of the Subtotal, Tax, Shipping and Special Handling does not match the GrossAmount in the InvoiceDetailSummary.
Solution
Ensure the GrossAmount the calculated sum of the Subtotal, Tax, Shipping and Special Handling as explained here: GrossAmount
Internal Server Error
<Status code="500" text="Internal Server Error"/>
An error has occurred trying to validate and process the invoice.
Solution
Contact Unimarket Support via support@unimarket.com to investigate this error further. Please also provide a copy of the cXML invoice to help with troubleshooting.