XML Input Structure for eShopCONNECTED Order Importer
Both eShopCONNECTED and Order Importer for Connected Business use the same base input XML Import message structure. However, the Order Importer requires the XML to be contained within a physical file, and the eShopCONNECTED base import module accepts data posted to the eShopCONNECTED Web Service via an HTTP web post.
XML has a number of advantages of the traditional comma separated variable input format used with previous generation systems. The main ones are that it is both human and machine readable, making it much easier to investigate input data errors, and it is inherently extendable so that new features can be added whilst maintaining compatibility with earlier versions. As a result, XML is rapidly becoming the format of choice for interface formats.
Download a Generic Order XML file here. You can use it as your default import source.
Basic XML Structure
All XML documents must have a single root node, but this can have many child nodes and each of these can in turn have many children of their own. Each node is identified by a start tag and an end tag identified by the characters < > and with a / before the node name for the end tag.
If the node has no child nodes (see ChildNode1 in the example below), the node value is contained between the start and end tags.
If the node does have its own children (see ChildNode2 in the example below), those child nodes are located contained between the start and end tags of the parent node (see ChildOfChildNode1 and ChildOfChildNode2 below).
At any level other than the root, a node can occur more than once (see ChildNode2 in the example below).
Coding Example
The example below is shown with the various child nodes indented. This is purely for the convenience of the human reader, the XML standard ignores any such formatting and it would be perfectly valid as a continuous string as shown in the second example.
Example XML structure with formatting
<RootNode>
<ChildNode1>value</ChildNode1>
<ChildNode2>
<ChildOfChildNode1>value</ChildOfChildNode1>
<ChildOfChildNode2>value1</ChildOfChildNode2>
</ChildNode2>
<ChildNode2>
<ChildOfChildNode1>value3</ChildOfChildNode1>
<ChildOfChildNode2>value4</ChildOfChildNode2>
</ChildNode2>
</RootNode>
Example XML structure without formatting
<RootNode><ChildNode1>value</ChildNode1><ChildNode2><ChildOfChildNode1>value</ChildOfChildNode1><ChildOfChildNode2>value1</ChildOfChildNode2></ChildNode2><ChildNode2><ChildOfChildNode1>value3</ChildOfChildNode1><ChildOfChildNode2>value4</ChildOfChildNode2></ChildNode2></RootNode>
3.1 Root Node and Core Child Nodes
| Node Name | eShopCONNECT |
| Parent Node | - |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed |
| Permitted Values/Notes | Child nodes as defined |
| Node Name | ImportType |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed |
| Permitted Values/Notes | Quote, Order, Invoice or Credit Note |
| Node Name | Source |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed |
| Permitted Values/Notes | Child nodes as defined |
| Node Name | SourceName |
| Parent Node | Source |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed |
| Permitted Values/Notes | Any Source name as shown in the eShopCONNECT or Order Importer Source Config |
| Node Name | SourceCode |
| Parent Node | Source |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed |
| Permitted Values/Notes | Any Source Code as shown in the eShopCONNECT or Order Importer Source Config |
| Node Name | Authentication |
| Parent Node | Source |
| Mandatory, Optional or Conditional | Conditional |
| Range | Only 1 instance allowed |
| Permitted Values/Notes | Required if a password has been created for the source in the eShopCONNECT or Order Importer Source Config |
| Node Name | Quote |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Conditional – required if ImportType = Quote |
| Range | 1 to * if ImportType = Quote, otherwise 0 |
| Permitted Values/Notes | See below for structure of a Quote Node |
| Node Name | Order |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Conditional – required if ImportType = Order |
| Range | 1 to * if ImportType = Order, otherwise 0 |
| Permitted Values/Notes | See below for structure of an Order Node |
| Node Name | Invoice |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Conditional – required if ImportType = Invoice |
| Range | 1 to * if ImportType = Invoice, otherwise 0 |
| Permitted Values/Notes | See below for structure of an Invoice Node |
| Node Name | CreditNote |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Conditional – required if ImportType = Credit Note |
| Range | 1 to * if ImportType = Credit Note, otherwise 0 |
| Permitted Values/Notes | See below for structure of an CreditNote Node |
| Node Name | QuoteCount |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Conditional – required if ImportType = Quote |
| Range | Only 1 instance allowed |
| Permitted Values/Notes | The number of Quote Nodes in the message |
| Node Name | OrderCount |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Conditional – required if ImportType = Order |
| Range | Only 1 instance allowed |
| Permitted Values/Notes | The number of Order Nodes in the message |
| Node Name | InvoiceCount |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Conditional – required if ImportType = Invoice |
| Range | Only 1 instance allowed |
| Permitted Values/Notes | The number of Invoice Nodes in the message |
| Node Name | CreditNoteCount |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Conditional – required if ImportType = Credit Note |
| Range | Only 1 instance allowed |
| Permitted Values/Notes | The number of Invoice Nodes in the message |
3.2 Quote Node and Child Nodes
| Node Name | Quote |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Conditional – required if ImportType = Quote |
| Range | 1 to * if ImportType = Quote, otherwise 0 |
| Permitted Values/Notes | Child nodes as defined |
| Node Name | CustomerOrderRef |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Optional, but if supplied, will be used along with SourceQuoteRef to check for Quote being imported previously. |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes | The Customer’s reference for the quote – will be inserted into the POCode field in Connected Business – maximum 30 characters |
| Node Name | SourceQuoteRef |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Optional, but if not supplied and message is processed twice, quote WILL be duplicated |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes | The reference for the quote as used by the Source – will be inserted in the MerchantOrderID_DEV000221 custom field in Connected Business – up to 30 alphanumeric characters |
| Node Name | SourceWebSiteRef |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes | Will be inserted into the WebSiteCode field in Connected Business – maximum 30 characters |
| Node Name | SourceMerchantID |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Conditional – required when quote status information is to be passed back to the source e.g. for Amazon, Shop.com etc |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes | Will be inserted in the StoreMerchantID_DEV000221 custom field in Connected Business – up to 30 alphanumeric characters |
| Node Name | QuoteDate |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes | The Date of the Quote in the form yyyy-mm-dd Must not be before 01/01/1900 or more than 50 years in the future |
| Node Name | QuoteCurrency |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes | The Currency for the Quote where different from the Connected Business base currency |
| Node Name | PricesIncludeTax |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes | If present, must be Yes or No. Defines whether all price values within the Quote are inclusive of Sales Tax (VAT) or not |
| Node Name | CustomerSalesCoupon |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Optional – may not be used on the same quote record as a DiscountCoupon node |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes |
A valid Connected Business Customer Sales Coupon Code NOTE: If a Customer Sales Coupon Code is provided, the ItemUnitPrice, ItemSubTotal and ItemTaxValue MUST be the value BEFORE the Coupon discount is calculated. |
| Node Name | CustomerSalesCoupon |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Optional – may not be used on the same quote record as a DiscountCoupon node |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes |
A valid Connected Business Customer Sales Coupon Code NOTE: If a Customer Sales Coupon Code is provided, the ItemUnitPrice, ItemSubTotal and ItemTaxValue MUST be the value BEFORE the Coupon discount is calculated. |
| Node Name | DiscountCoupon |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Optional – must not be used on the same quote record as CustomerSalesCoupon |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes |
See below for structure of a DiscountCoupon Node |
| Node Name | CustomField |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Optional – If present, the database field name must be specified in the FieldName attribute |
| Range | 1 to * - One instance required for each Custom Field to be set in the CustomerSalesOrder table of the Connected Business database |
| Permitted Values/Notes |
Any value which is valid for the specified custom field. |
| Node Name | BillingDetails |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes |
See below for structure of a BillingDetails Node |
| Node Name | ShippingDetails |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Conditional – required if Quote shipping address is different from Billing address |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes |
See below for structure of a ShippingDetails Node |
| Node Name | Item |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Mandatory – At least 1 instance required per Quote |
| Range | 1 to * - One instance required for each Quote Item |
| Permitted Values/Notes |
See below for structure of a Item Node |
| Node Name | QuoteTotals |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes |
See below for structure of a QuoteTotals Node |
| Node Name | CustomerComments |
| Parent Node | Quote |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes |
Any comments/special instructions from the Customer for the quote – will be inserted into the Notes field in Connected Business – maximum 255 characters |
3.3 Order Node and child nodes
| Node Name | Order |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Conditional – required if ImportType = Order |
| Range | 1 to * if ImportType = Order, otherwise 0 |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | CustomerOrderRef |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Optional, but if supplied, will be used along with SourceOrderRef to check for Order being imported previously. |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
The Customer’s reference for the order – will be inserted into the POCode field in Connected Business – maximum 30 characters |
| Node Name | SourceOrderRef |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Optional, but if not supplied and message is processed twice, order WILL be duplicated |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
The reference for the order as used by the Source – will be inserted in the MerchantOrderID_DEV000221 custom field in Connected Business – up to 30 alphanumeric characters |
| Node Name | SourceWebSiteRef |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
Will be inserted into the WebSiteCode field in Connected Business – maximum 30 characters |
| Node Name | SourceMerchantID |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Conditional – required when order status information is to be passed back to the source e.g. for Amazon, Shop.com etc |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
Will be inserted in the StoreMerchantID_DEV000221 custom field in Connected Business – up to 30 alphanumeric characters |
| Node Name | OrderDate |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
The Date of the Order in the form yyyy-mm-dd Must not be before 01/01/1900 or more than 50 years in the future |
| Node Name | OrderCurrency |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
The Currency for the Order where different from the Connected Business base currency |
| Node Name | PricesIncludeTax |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
If present, must be Yes or No. Defines whether all price values within the Order are inclusive of Sales Tax (VAT) or not |
| Node Name | CustomerSalesCoupon |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Optional – may not be used on the same order record as a DiscountCoupon node |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
A valid Connected Business Customer Sales Coupon Code NOTE: If a Customer Sales Coupon Code is provided, the ItemUnitPrice, ItemSubTotal and ItemTaxValue MUST be the value BEFORE the Coupon discount is calculated. |
| Node Name | DiscountCoupon |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Optional – must not be used on the same order record as CustomerSalesCoupon |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
See below for structure of a DiscountCoupon Node |
| Node Name | CustomField |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Optional – If present, the database field name must be specified in the FieldName attribute |
| Range | 1 to * - One instance required for each Custom Field to be set in the CustomerSalesOrder table of the Connected Business database |
| Permitted Values/Notes |
Any value which is valid for the specified custom field. |
| Node Name | BillingDetails |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
See below for structure of a BillingDetails Node |
| Node Name | ShippingDetails |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Conditional – required if Order shipping address is different from Billing address |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
See below for structure of a ShippingDetails Node |
| Node Name | PaymentDetails |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Conditional – required if a credit card payment is to be processed or a payment record is to be created |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
See below for structure of a PaymentDetails Node |
| Node Name | Item |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Mandatory – At least 1 instance required per Order |
| Range | 1 to * - One instance required for each Order Item |
| Permitted Values/Notes |
See below for structure of a Item Node |
| Node Name | OrderTotals |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
See below for structure of a OrderTotals Node |
| Node Name | CustomerComments |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
Any comments/special instructions from the Customer for the order – will be inserted into the Notes field in Connected Business – maximum 255 characters |
| Node Name | OrderTotals |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
See below for structure of a OrderTotals Node |
| Node Name | CustomerComments |
| Parent Node | Order |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
Any comments/special instructions from the Customer for the order – will be inserted into the Notes field in Connected Business – maximum 255 characters |
3.4 Invoice Node and child nodes
| Node Name | Invoice |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Conditional – required if ImportType = Invoice |
| Range | 1 to * if ImportType = Invoice, otherwise 0 |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | CustomerOrderRef |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Optional, but if supplied, will be used along with SourceInvoiceRef to check for Invoice being imported previously. |
| Range | Only 1 instance allowed per Invoice nodee 0 |
| Permitted Values/Notes |
The Customer’s reference for the order – will be inserted into the POCode field in Connected Business – maximum 30 characters |
| Node Name | SourceInvoiceRef |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Optional, but if not supplied and message is processed twice, Invoice WILL be duplicated |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
The reference for the invoice as used by the Source – will be inserted in the MerchantOrderID_DEV000221 custom field in Connected Business – up to 30 alphanumeric characters |
| Node Name | SourceWebSiteRef |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
Will be inserted into the WebSiteCode field in Connected Business – maximum 30 characters |
| Node Name | SourceMerchantID |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
Will be inserted in the StoreMerchantID_DEV000221 custom field in Connected Business – up to 30 alphanumeric characters |
| Node Name | InvoiceDate |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
The Date of the Invoice in the form yyyy-mm-dd Must not be before 01/01/1900 or more than 50 years in the future |
| Node Name | InvoiceDate |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
The Date of the Invoice in the form yyyy-mm-dd Must not be before 01/01/1900 or more than 50 years in the future |
| Node Name | InvoiceCurrency |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
The Currency for the Invoice where different from the Connected Business base currency |
| Node Name | PricesIncludeTax |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
If present, must be Yes or No. Defines whether all price values within the Invoice are inclusive of Sales Tax (VAT) or not |
| Node Name | CustomField |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Optional – If present, the database field name must be specified in the FieldName attribute |
| Range | 1 to * - One instance required for each Custom Field to be set in the CustomerInvoice table of the Connected Business database |
| Permitted Values/Notes |
Any value which is valid for the specified custom field. |
| Node Name | PostInvoice |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
If present, must be Yes or No. Defines whether the Invoice is to be Posted after creation or not |
| Node Name | BillingDetails |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
See below for structure of a BillingDetails Node |
| Node Name | ShippingDetails |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Conditional – required if Invoice shipping address is different from Billing address |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
See below for structure of a ShippingDetails Node |
| Node Name | PaymentDetails |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Conditional – required if a credit card payment is to be processed or a payment record is to be created |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
See below for structure of a PaymentDetails Node |
| Node Name | Item |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Mandatory – At least 1 instance required per Invoice |
| Range | 1 to * - One instance required for each Invoice Item |
| Permitted Values/Notes |
See below for structure of a Item Node |
| Node Name | InvoiceTotals |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
See below for structure of a InvoiceTotals Node |
| Node Name | CustomerComments |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
Any comments/special instructions from the Customer for the Invoice – will be inserted into the Notes field in Connected Business – maximum 255 characters |
3.5 Credit Note Node and child nodes
| Node Name | CreditNote |
| Parent Node | eShopCONNECT |
| Mandatory, Optional or Conditional | Conditional – required if ImportType = Credit Note |
| Range | 1 to * if ImportType = Credit Note, otherwise 0 |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | CustomerOrderRef |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Optional, but if supplied, will be used along with SourceCreditNoteRef to check for Credit Note being imported previously. |
| Range | Only 1 instance allowed per CreditNote node |
| Permitted Values/Notes |
The Customer’s reference for the order – will be inserted into the POCode field in Connected Business – maximum 30 characters |
| Node Name | SourceCreditNoteRef |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Optional, but if not supplied and message is processed twice, Credit Note WILL be duplicated |
| Range | Only 1 instance allowed per CreditNote node |
| Permitted Values/Notes |
The reference for the credit note as used by the Source – will be inserted in the MerchantOrderID_DEV000221 custom field in Connected Business – up to 30 alphanumeric characters |
| Node Name | SourceWebSiteRef |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per CreditNote node |
| Permitted Values/Notes |
Will be inserted into the WebSiteCode field in Connected Business – maximum 30 characters |
| Node Name | SourceMerchantID |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per CreditNote node |
| Permitted Values/Notes |
Will be inserted in the StoreMerchantID_DEV000221 custom field in Connected Business – up to 30 alphanumeric characters |
| Node Name | CreditNoteDate |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per CreditNote node |
| Permitted Values/Notes |
The Date of the Credit Note in the form yyyy-mm-dd Must not be before 01/01/1900 or more than 50 years in the future |
| Node Name | CreditNoteCurrency |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per CreditNote node |
| Permitted Values/Notes |
The Currency for the Credit Note where different from the Connected Business base currency |
| Node Name | PricesIncludeTax |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per CreditNote node |
| Permitted Values/Notes |
If present, must be Yes or No. Defines whether all price values within the Credit Note are inclusive of Sales Tax (VAT) or not |
| Node Name | CustomField |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Optional – If present, the database field name must be specified in the FieldName attribute |
| Range | 1 to * - One instance required for each Custom Field to be set in the CustomerInvoice table of the Connected Business database |
| Permitted Values/Notes |
Any value which is valid for the specified custom field. |
| Node Name | BillingDetails |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per CreditNote node |
| Permitted Values/Notes |
See below for structure of a BillingDetails Node |
| Node Name | ShippingDetails |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Conditional – required if Credit Note shipping address is different from Billing address |
| Range | Only 1 instance allowed per CreditNote node |
| Permitted Values/Notes |
See below for structure of a ShippingDetails Node |
| Node Name | Item |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Mandatory – At least 1 instance required per Credit Note |
| Range | 1 to * - One instance required for each Credit Note Item |
| Permitted Values/Notes |
See below for structure of a Item Node |
| Node Name | CreditNoteTotals |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per CreditNote node |
| Permitted Values/Notes |
See below for structure of a CreditNoteTotals Node |
| Node Name | CustomerComments |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per CreditNote node |
| Permitted Values/Notes |
Any comments/special instructions from the Customer for the Credit Note – will be inserted into the Notes field in Connected Business – maximum 255 characters |
3.6 Billing Details Node and child nodes
| Node Name | BillingDetails |
| Parent Node | Order, Invoice or CreditNote depending on ImportType value |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per Order, Invoice or CreditNote node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | Customer |
| Parent Node | BillingDetails |
| Mandatory, Optional or Conditional | Mandatory |
| Range | Only 1 instance allowed per BillingDetails node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | SourceCustomerID |
| Parent Node | Customer |
| Mandatory, Optional or Conditional | Conditional – See section below on identification of Customers |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
Will be inserted in the ImportCustomerID_DEV000221 custom field of the Customer table in Connected Business – up to 30 alphanumeric characters |
| Node Name | ISCustomerCode |
| Parent Node | Customer |
| Mandatory, Optional or Conditional | Conditional – See section below on identification of Customers |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
A CustomerCode for a customer that exists in the Connected Business database |
| Node Name | NamePrefix |
| Parent Node | Customer |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
Any valid Connected Business Salutation |
| Node Name | FirstName |
| Parent Node | Customer |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
Any valid Connected Business Salutation |
| Node Name | LastName |
| Parent Node | Customer |
| Mandatory, Optional or Conditional | Conditional – Must be present if NamePrefix or FirstName are present and mandatory when creating a new customer record in the Connected Business database |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
| Node Name | Company |
| Parent Node | Customer |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
| Node Name | HomePhone |
| Parent Node | Customer |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
See section 6 below for details of how telephone numbers are mapped to Connected Business |
| Node Name | WorkPhone |
| Parent Node | Customer |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
See section 6 below for details of how telephone numbers are mapped to Connected Business |
| Node Name | MobilePhone |
| Parent Node | Customer |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
See section 6 below for details of how telephone numbers are mapped to Connected Business |
| Node Name | |
| Parent Node | Customer |
| Mandatory, Optional or Conditional | Optional |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
| Node Name | CustomField |
| Parent Node | Customer |
| Mandatory, Optional or Conditional |
Conditional – If present, the database field name must be specified in the FieldName attribute Only used when a new customer record is created in the Connected Business database, otherwise ignored |
| Range | 1 to * - One instance required for each Custom Field to be set in the Customer table of the Connected Business database |
| Permitted Values/Notes |
Any value which is valid for the specified custom field. |
| Node Name | BillingAddress |
| Parent Node | BillingDetails |
| Mandatory, Optional or Conditional |
Conditional – Must be present when a new customer record is created in the Connected Business database |
| Range | Only 1 instance allowed per BillingDetails node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | Address |
| Parent Node | BillingDetails |
| Mandatory, Optional or Conditional |
Conditional – Must be present when a new customer record is created in the Connected Business database or if any of Town_City, County, State, PostalCode or Country are present |
| Range | Only 1 instance allowed per BillingAddress node |
| Permitted Values/Notes |
| Node Name | Town_City |
| Parent Node | BillingDetails |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per BillingAddress node |
| Permitted Values/Notes |
| Node Name | County |
| Parent Node | BillingDetails |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per BillingAddress node |
| Permitted Values/Notes |
| Node Name | State |
| Parent Node | BillingDetails |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per BillingAddress node |
| Permitted Values/Notes |
| Node Name | PostalCode |
| Parent Node | BillingDetails |
| Mandatory, Optional or Conditional |
Conditional – Must be present when a new customer record is created in the Connected Business database or if any of Address, Town_City, County, State or Country are present |
| Range | Only 1 instance allowed per BillingAddress node |
| Permitted Values/Notes |
| Node Name | Country |
| Parent Node | BillingDetails |
| Mandatory, Optional or Conditional |
Conditional – Must be present when a new customer record is created in the Connected Business database or if any of Address, Town_City, County, State or PostalCode are present |
| Range | Only 1 instance allowed per BillingAddress node |
| Permitted Values/Notes |
Any valid Connected Business Country Code |
3.7 Shipping Details Node and child nodes
| Node Name | ShippingDetails |
| Parent Node | Order, Invoice or CreditNote depending on ImportType value |
| Mandatory, Optional or Conditional |
Optional – only required if Shipping Address differs from Billing Address |
| Range | Only 1 instance allowed per Order, Invoice or CreditNote node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | Customer |
| Parent Node | ShippingDetails |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per ShippingDetails node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | NamePrefix |
| Parent Node | Customer |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
Any valid Connected Business Salutation |
| Node Name | FirstName |
| Parent Node | Customer |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
| Node Name | LastName |
| Parent Node | Customer |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
| Node Name | Company |
| Parent Node | Customer |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
| Node Name | Telephone |
| Parent Node | Customer |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
See section 6 below for details of how telephone numbers are mapped to Connected Business |
| Node Name | |
| Parent Node | Customer |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Customer node |
| Permitted Values/Notes |
| Node Name | ShippingAddress |
| Parent Node | ShippingDetails |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per ShippingDetails node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | Address |
| Parent Node | ShippingAddress |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per ShippingAddress node |
| Permitted Values/Notes |
| Node Name | Town_City |
| Parent Node | ShippingAddress |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per ShippingAddress node |
| Permitted Values/Notes |
| Node Name | State |
| Parent Node | ShippingAddress |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per ShippingAddress node |
| Permitted Values/Notes |
| Node Name | County |
| Parent Node | ShippingAddress |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per ShippingAddress node |
| Permitted Values/Notes |
| Node Name | PostalCode |
| Parent Node | ShippingAddress |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per ShippingAddress node |
| Permitted Values/Notes |
| Node Name | Country |
| Parent Node | ShippingAddress |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per ShippingAddress node |
| Permitted Values/Notes |
Any valid Connected Business Country Code |
3.8 Coupon Discount Node and child nodes
| Node Name | DiscountCoupon |
| Parent Node | Order |
| Mandatory, Optional or Conditional |
Optional – must not be used on the same order record as CustomerSalesCoupon |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | DiscountDescription |
| Parent Node | DiscountCoupon |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per DiscountCoupon node |
| Permitted Values/Notes |
The description of the discount which will be used as the description of the single use Sales Coupon to be created and applied to the Order |
| Node Name | DiscountValue |
| Parent Node | DiscountCoupon |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per DiscountCoupon node |
| Permitted Values/Notes |
The value of the single use Sales Coupon to be created and applied to the Order – must be numeric |
3.9 Payment Details Node and child nodes
| Node Name | PaymentDetails |
| Parent Node | Order or Invoice depending on ImportType value |
| Mandatory, Optional or Conditional |
Conditional – required if a credit card payment is to be processed or a payment record is to be created |
| Range | Only 1 instance allowed per Order or Invoice node – Not valid in CreditNote nodes |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | PaymentMethod |
| Parent Node | PaymentDetails |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per PaymentDetails node |
| Permitted Values/Notes |
Credit Card or Source |
| Node Name | PaymentType |
| Parent Node | PaymentDetails |
| Mandatory, Optional or Conditional |
Conditional – required if PaymentMethod = Source |
| Range | Only 1 instance allowed per PaymentDetails node |
| Permitted Values/Notes |
Any valid Connected Business Payment Method |
| Node Name | PaymentDate |
| Parent Node | PaymentDetails |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per PaymentDetails node |
| Permitted Values/Notes |
The Date of the Payment in the form yyyy-mm-dd Must not be before 01/01/1900 or more than 50 years in the future. Only required if different from the Order/Invoice date. |
| Node Name | CreditCardDetails |
| Parent Node | PaymentDetails |
| Mandatory, Optional or Conditional |
Conditional – required if PaymentMethod = Credit Card |
| Range | Only 1 instance allowed per PaymentDetails node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | NameOnCard |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The name on the Credit Card |
| Node Name | CardType |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
Any Credit Card type which is configured as active within Connected Business |
| Node Name | CardIssuer |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The issuing bank for the Credit Card |
| Node Name | CardNumber |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The issuing bank for the Credit Card |
| Node Name | CardStartDate |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The Start or Valid From date on the card in the form mm/yy |
| Node Name | CardExpiryDate |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The Expiry or Valid To date on the card in the form mm/yy |
| Node Name | CardSecurityNumber |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Conditional – Depends on the current requirements of the Card Issuer and Payment Gateway in use |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The security number from the reverse of the Credit Card |
| Node Name | CardIssueNumber |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Conditional – Depends on the Credit Card Type |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The issue number on the card |
| Node Name | TransactionStatus |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
If blank or set to AuthoriseCard and the config setting AuthoriseCreditCardOnImport is set to Yes, an attempt will be made to obtain a card authorization via the Connected Business credit card gateway. If set to CardAuthorised, an Authorisation record will be created for subsequent capture when the Invoice is posted. If set to PaymentReceived, a payment record will be created for the Order/Invoice See note below re use of CardAuthorised value |
| Node Name | AuthorisationNumber |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Conditional – Required if TransactionStatus = CardAuthorised or PaymentReceived |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The Authorisation Number issued by the credit card processor for the card transaction |
| Node Name | AuthorisationNumber |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Conditional – Required if TransactionStatus = CardAuthorised or PaymentReceived |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The Authorisation Number issued by the credit card processor for the card transaction |
| Node Name | SourceCardTransactionID |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Conditional – Required if TransactionStatus = CardAuthorised |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The Transaction ID used by the Source to identify the card transaction. |
| Node Name | GatewayTransactionID |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Conditional – Required if TransactionStatus = CardAuthorised |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The Transaction ID provided by the Payment Gateway provider to identify the card transaction. |
| Node Name | GatewayResponseAVS |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Conditional – Required if TransactionStatus = CardAuthorised |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The AVS Response from the Payment Gateway provider. |
| Node Name | GatewayResponseCVV |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Conditional – Required if TransactionStatus = CardAuthorised |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The CVV Response from the Payment Gateway provider. |
| Node Name | GatewayResponseText |
| Parent Node | CreditCardDetails |
| Mandatory, Optional or Conditional |
Conditional – Required if TransactionStatus = CardAuthorised |
| Range | Only 1 instance allowed per CreditCardDetails node |
| Permitted Values/Notes |
The full Gateway response from the Payment Gateway provider in the form that It would appear in the Connected Business CustomerCCAuthResponse table. |
| Node Name | SourcePaymentID |
| Parent Node | PaymentDetails |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per PaymentDetails node |
| Permitted Values/Notes |
The reference for the payment as used by the Source – will be inserted in the FirstReference field of the Banking Deposit table in Connected Business – up to 50 alphanumeric characters |
Using a TransactionStatus value of CardAuthorised is only possible where the external source system uses the same payment provider as Connected Business and requires considerable initial setup to ensure that the correct values are provided for AuthorisationNumber, SourceCardTransactionID, GatewayTransactionID, GatewayResponseAVS, GatewayResponseCVV and GatewayResponseText in the format required by the specific payment gateway selected in Connected Business.
It is recommended that this option is only used where no other solution is possible.
3.10 Item Node and child nodes
| Node Name | Item |
| Parent Node | Order, Invoice or CreditNote depending on ImportType value |
| Mandatory, Optional or Conditional |
Mandatory – At least 1 instance required per Order, Invoice or Credit Note |
| Range | 1 to * - One instance required for each Order, Invoice or CreditNote Item |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | SourceItemPurchaseID |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
The reference for the order item as used by the Source – will be inserted in the SourcePurchaseID_DEV000221 custom field in Connected Business – up to 30 alphanumeric characters |
| Node Name | ISItemCode |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Conditional – either ISItemCode or ISItemName must be provided. If both are present, the ISItemCode will be used |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
A valid ItemCode for an Inventory Item which is active in the Connected Business database |
| Node Name | ISItemName |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Conditional – either ISItemCode or ISItemName must be provided. If both are present, the ISItemCode will be used |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
A valid ItemName for an Inventory Item which is active in the Connected Business database |
| Node Name | ItemUnitOfMeasure |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
The Connected Business Unit of Measure for the item – if not provided, the Connected Business default Unit of Measure will be applied |
| Node Name | ItemWarehouse |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
The Connected Business Warehouse for the item – if not provided, the default warehouse specified in the source config settings will be applied |
| Node Name | ItemDescription |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
The Description to be used for the Item on the Order, Invoice or Credit Note |
| Node Name | ItemDropShip |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
If present, must be Yes or No. Defines whether the Item is to be drop shipped |
| Node Name | DropShipReference |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Conditional – Only valid if ItemDropShip is Yes |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
The Reference to be used for the Drop Ship |
| Node Name | ItemQuantity |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
The Quantity to be used for the Item on the Order, Invoice or Credit Note – must be numeric |
| Node Name | ItemUnitPrice |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Optional – If not provided, price will default to Connected Business default for customer |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
The Unit Price to be used for the Item on the Order, Invoice or Credit Note – must be numeric |
| Node Name | ItemSubTotal |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
The Sub Total to be used for the Item on the Order, Invoice or Credit Note – must be numeric and the product of the Unit Price and the Item Quantity |
| Node Name | ItemTaxRate |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
The Tax Rate (Sales Tax, VAT etc) to be used for the Item on the Order, Invoice or Credit Note – must be numeric |
| Node Name | ItemTaxValue |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
The value of the Tax (Sales Tax, VAT etc) to be used for the Item on the Order, Invoice or Credit Note – must be numeric and the product of the Item Sub Total and the Item Tax Rate |
| Node Name | SourceItemCommission |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
The value of any Commission or Fees to be paid for the Item on the Order, Invoice or Credit Note – must be numeric |
| Node Name | SourceItemFulfillmentCharge |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Optional |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
The value of any Fulfillment Charge or Fees to be paid for the Item on the Order, Invoice or Credit Note – must be numeric |
| Node Name | SpecialInstructions |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Optional – Reserved for future use |
| Range | Only 1 instance allowed per Item node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | SpecialInstructionType |
| Parent Node | SpecialInstructions |
| Mandatory, Optional or Conditional |
Optional – Reserved for future use |
| Range | Only 1 instance allowed per SpecialInstructions node |
| Permitted Values/Notes |
| Node Name | SpecialInstructionDetail |
| Parent Node | SpecialInstructions |
| Mandatory, Optional or Conditional |
Optional – Reserved for future use |
| Range | Only 1 instance allowed per SpecialInstructions node |
| Permitted Values/Notes |
| Node Name | CustomField |
| Parent Node | Item |
| Mandatory, Optional or Conditional |
Optional – If present, the database field name must be specified in the FieldName attribute |
| Range | 1 to * - One instance required for each Custom Field to be set in the CustomerSalesOrderDetaail table of the Connected Business database |
| Permitted Values/Notes |
Any value which is valid for the specified custom field. |
3.11 Quote Totals Node and child nodes
| Node Name | QuoteTotals |
| Parent Node | Quote |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per Quote node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | SubTotal |
| Parent Node | QuoteTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per QuoteTotals node |
| Permitted Values/Notes |
The sum of the SubTotal node for every Item on the quote |
| Node Name | Shipping |
| Parent Node | QuoteTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per QuoteTotals node |
| Permitted Values/Notes |
The Shipping charge for the quote (excluding tax) |
| Node Name | Tax |
| Parent Node | QuoteTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per QuoteTotals node |
| Permitted Values/Notes |
The Tax (Sales Tax, VAT, etc) due on the quote |
|
3.12 Order Totals Node and child nodes
| Node Name | OrderTotals |
| Parent Node | Order |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per Order node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | SubTotal |
| Parent Node | OrderTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per OrderTotals node |
| Permitted Values/Notes |
The sum of the SubTotal node for every Item on the order |
| Node Name | Shipping |
| Parent Node | OrderTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per OrderTotals node |
| Permitted Values/Notes |
The Shipping charge for the order (excluding tax) |
| Node Name | Tax |
| Parent Node | OrderTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per OrderTotals node |
| Permitted Values/Notes |
The Tax (Sales Tax, VAT, etc) due on the order |
| Node Name | Tax |
| Parent Node | OrderTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per OrderTotals node |
| Permitted Values/Notes |
The Tax (Sales Tax, VAT, etc) due on the order |
| Node Name | Total |
| Parent Node | OrderTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per OrderTotals node |
| Permitted Values/Notes |
The Total value of the order and the sum of the SubTotal + Shipping + Tax nodes |
3.13 Invoice Totals Node and child nodes
| Node Name | InvoiceTotals |
| Parent Node | Invoice |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per Invoice node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | SubTotal |
| Parent Node | InvoiceTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per InvoiceTotals node |
| Permitted Values/Notes |
The sum of the SubTotal node for every Item on the invoice |
| Node Name | Shipping |
| Parent Node | InvoiceTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per InvoiceTotals node |
| Permitted Values/Notes |
The Shipping charge for the invoice (excluding tax) |
| Node Name | Tax |
| Parent Node | InvoiceTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per InvoiceTotals node |
| Permitted Values/Notes |
The Tax (Sales Tax, VAT, etc) due on the invoice |
| Node Name | Total |
| Parent Node | InvoiceTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per InvoiceTotals node |
| Permitted Values/Notes |
The Total value of the invoice and the sum of the SubTotal + Shipping + Tax nodes |
3.14 Credit Note Totals Node and child nodes
| Node Name | CreditNoteTotals |
| Parent Node | CreditNote |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per CreditNote node |
| Permitted Values/Notes |
Child nodes as defined |
| Node Name | SubTotal |
| Parent Node | CreditNoteTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per CreditNoteTotals node |
| Permitted Values/Notes |
The sum of the SubTotal node for every Item on the credit note |
| Node Name | Shipping |
| Parent Node | CreditNoteTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per CreditNoteTotals node |
| Permitted Values/Notes |
The Shipping charge for the credit note (excluding tax) |
| Node Name | Tax |
| Parent Node | CreditNoteTotals |
| Mandatory, Optional or Conditional |
Mandatory |
| Range | Only 1 instance allowed per CreditNoteTotals node |
| Permitted Values/Notes |
The Tax (Sales Tax, VAT, etc) due on the credit note |
XML Predefined Entities
The XML standard defines five "Predefined Entities" representing special characters, and requires that all XML processors honor them. Accordingly, if the value to be included in any Node for an XML import message for eShopCONNECT or Order Importer for Connected Business must have the following characters substituted with their entity equivalents:
| Character | To be substituted by:- | Name |
| Node Name | & | Ampersand |
| Parent Node | " | Quotation mark |
| Mandatory, Optional or Conditional | ' |
Apostrophe |
| Range | < | Less than |
| Permitted Values/Notes | > |
Greater than |
Depending on how this substitution is implemented, the order in which the substitutions are performed can be critical because the Ampersand character appears in the substitution outputs.
Customer identification in Import Records
The XML Import message structure used by eShopCONNECT and Order Importer for Connected Business contains 2 XML elements which can be used to identify the target customer for an imported Quote, Order, Invoice or Credit Note. These are the ISCustomerCode and SourceCustomerID in the Billing Details node and they provide the means of matching customer records between Connected Business Suite and the external system from which orders etc. are being imported.
How they are used depends on how customers are identified in the external system. If the Connected Business Suite Customer Code is used by the external system, then the ISCustomerCode element is the only one needed to identify a customer in the import record.
More usually however, the external system will have its own ID for each customer and have no record of the Connected Business Suite Customer Code. In this case, the SourceCustomerID element should be included in the import record.
If the ISCustomerCode element is populated, it must contain a valid Connected Business Customer Code which exists in the target database. If a marching Customer record is not found, the import file will be rejected.
If the ISCustomerCode element is blank. the SourceCustomerID will be used to identify the target customer. If it is populated, the Order Importer will query the Connected Business Customer table for a customer record with the ImportSourceID_DEV000221 custom field set to the name of the import source e.g. Generic XML import and the ImportCustomerID_DEV000221 custom field set to the SourceCustomerID value.
If a matching record is found, the imported order, invoice or credit note will be created for that customer, otherwise a new customer record will be created.
If both the ISCustomerCode and SourceCustomerID elements are blank, then the Order Importer will not be able to match the imported record to an existing customer. In this case, the RequireSourceCustomerID configuration setting comes into play. If this is set to Yes, then the imported file is rejected. If it is set to No, the imported file will be processed and a new customer record created, unless the imported record is a Credit Note.
If RequireSourceCustomerID is set to No and both the ISCustomerCode and SourceCustomerID elements are blank, a new customer record will ALWAYS be created for each new order or invoice.
Credit Note imports will ALWAYS be rejected if RequireSourceCustomerID is set to No and both the ISCustomerCode and SourceCustomerID elements are blank.
Importing of Telephone Numbers into Connected Business
The standard data structures of Connected Business do not provide fields for all the telephone number fields allowed in the XML Import message structure used by eShopCONNECT and Order Importer for Connected Business and some processing logic is therefore applied when creating Customer records, their related CRM Contact records and Sales Orders, Invoices and Credit Notes.
An Connected Business Customer record only has a single telephone number field so the Company XML element in the BillingDetails/Customer Node is checked to determine how the HomePhone and WorkPhone XML elements in the BillingDetails/Customer Node are mapped to the Connected Business Customer table Telephone field. If the Company XML element is populated, the customer details are assumed to be for a company and the Connected Business Customer Telephone field is populated with the WorkPhone XML element. If the Company XML element is blank or omitted, the customer details are assumed to be for an individual and the Connected Business Customer Telephone field is populated with the HomePhone XML element.
The Connected Business Customer Ship To record also has a single telephone number field and this is populated with the Telephone XML element in the ShippingDetails/Customer Node.
An Connected Business Contact record has Home, business and Mobile telephone number fields, although the Home telephone number is not normally displayed, and the HomePhone, WorkPhone and MobilePhone XML elements in the BillingDetails/Customer Node are copied directly to the corresponding field on the Connected Business CRMContact table.
The Connected Business Customer Sales Order, Customer Invoice and Customer Credit Note/Credit Memo records all have a single Bill To telephone number and a single Ship To telephone number. These are populated exactly the same way as the corresponding Customer and Customer Ship To telephone numbers