Purchase Orders
-
Order Integration Overview
The Order integration is used to communicate order details between Unimarket and an external system. The Order integration sends a cXML file via an HTTPS connection.
Why use this integration?
This integration is used to send Purchase Orders with Product Details to a Supplier when a Purchase Order is generated within Unimarket. This allows the Orders to be electronically entered into a Suppliers system which makes the process instant and once properly configured, less prone to errors compared to manually entering orders.
Where to find it?
Current order integration setups can be found and edited in Profile > Configure Store > Integration. If a new point of integration needs to be established, click on Add Order Integration Point and fill out the applicable details before hitting Add to confirm.
Note: With any new integration points or updates, formal testing needs to be done first before entering new information. If you need to modify an existing integration setup or create a new one, please reach out to support@unimarket.com. Supplier Setup
The following details are required by Unimarket to setup the integration within Unimarket
Field Purpose Dispatch Mechanism Determines how the electronic message will be sent to the supplier. This must be set to the mechanism the supplier supports. URL This is the URL where the electronic PO's will be sent. The supplier will provide the URL. If a Gateway such as Tranzsoft is being used to pass messages between Unimarket and the supplier then the URL will be the gateway URL not the supplier URL. The supplier or Gateway service provider will provide this. FROM Credential Domain This identifies the Community Domain where the orders are being sent from. This is the key information for the supplier to identify the customer that is sending them the order. If the supplier sets the 'FROM Credential Identity' as their DUNS number then this is usually set to the word DUNS (but can be anything). FROM Credential Identity This identifies the Community where the orders are being sent from. This is the key information for the supplier to identify the customer that is sending them the order. It can be set to anything but it is commonly set to the Communities DUNS number. TO Credential Domain This identifies the Supplier Domain where the orders are being sent to. If the supplier sets the 'TO Credential Identity' as their DUNS number then this is usually set to the word DUNS (but can be anything). It is rarely verified by the supplier. TO Credential Identity This Supplier Identity where the orders are being sent to. It is commonly set to the suppliers DUNS number (but can be anything). It is rarely verified by the supplier. Shared Secret This is a password that must be set within Unimarket and within the supplier's system. The 2 must match. You can find the technical information on our Purchase Order Integration help page.
Note: Outbound order integration can now be set to include Requester information instead of Buyer information. This is a setting that Unimarket will need to enable. -
Purchase Order Integration
Overview
Purchase Order Integration uses the cXML standard to send orders to suppliers from Unimarket.
This will be sent to a HTTP(S) endpoint using the POST method containing the cXML payload. Ideally this should be secured by TLS1.2.
In this Article
Example Basic Purchase Order
<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="[A Unique Value]" timestamp="2020-11-16T12:17:51.945+13:00" version="1.2.021" xml:lang="en">
<Header>
<From>...</From>
<To>...</To>
<Sender>...</Sender>
</Header>
<Request deploymentMode="test">
<OrderRequest>
<OrderRequestHeader orderDate="2020-11-16T12:17:51.124+13:00" orderID="102" orderType="regular" type="new">
<Total>
<Money currency="NZD">5.75</Money>
</Total>
<ShipTo>...</ShipTo>
<BillTo>...</BillTo>
<Shipping>...</Shipping>
<Tax>...</Tax>
<Contact role="buyer">...</Contact>
<Extrinsic name="buyer-credential">...</Extrinsic>
<Extrinsic name="shippingNote"/>
</OrderRequestHeader>
<ItemOut lineNumber="1" quantity="1" requisitionID="56">...</ItemOut>
<ItemOut lineNumber="2" quantity="4" requisitionID="56">...</ItemOut>
</OrderRequest>
</Request>
</cXML>
Header
The Purchase Order starts with the Header which can used to authenticate the message and understand which customer this has been sent from.
<Header>
<From>
<Credential domain="DUNS">
<Identity>CUSTOMER IDENTIFIER</Identity>
</Credential>
</From>
<To>
<Credential domain="DUNS">
<Identity>SUPPLIER IDENTIFIER</Identity>
</Credential>
</To>
<Sender>
<Credential domain="DUNS">
<Identity>CUSTOMER/SYSTEM IDENTIFIER</Identity>
<SharedSecret>SHAREDSECRET</SharedSecret>
</Credential>
<UserAgent>unimarket</UserAgent>
</Sender>
</Header>The From Credential domain attribute and Identity element are used to identify the Customer who raised the purchase order.
The To Credential domain attribute and Identity element are used to identify the Supplier the purchase order has been sent to.
The Sender Credential domain attribute and Identity element are used to identify the Customer or System that has sent the purchase order. The SharedSecret element is used for authentication.
Request
The Request element contains the the OrderRequest and shows if this purchase order has been sent from a Test or Production environment.
Test:
<Request deploymentMode="test">
Production:
<Request deploymentMode="production">
OrderRequest
The OrderRequest contains attributes that describe the orderDate, orderID, orderType and type.
<OrderRequestHeader orderDate="2020-11-16T12:17:51.124+13:00" orderID="102" orderType="regular" type="new">
The orderDate attribute is the date and time the order was generated in the format:
YYYY-MM-DD'T'hh:mm:ss.SSSZ
The orderID attribute is the purchase order number.
The orderType attribute is the type of order this is. This could be: "regular" or "blanket".
The type is the status of the order:
new - This is a new order.
update - This means the order has been updated. The order will contain all details as they have been updated. Two new attributes will now be included in OrderRequest: orderVersion and isInternalVersion.
The orderVersion attribute shows the version number for this order. It will start from 2 and increase.
The isInternalVersion attribute is a flag that indicates if this change should be hidden from the supplier. This will be set to "no".
delete - This means the order has been cancelled.
Note: The setting to enable/disable Allow Edit Orders and Allow Cancel Orders can ben found in the Configure Store screen in the Profile menu.
Total
The total element contains the Money Element. The Money element shows the total value of all items included in the order including taxes. The currency attribute shows the currency code.
<Total>
<Money currency="NZD">5.75</Money>
</Total>
ShipTo
This ShipTo element contains address information on where the customer would like the order to be delivered.
<ShipTo>
<Address addressID="101" isoCountryCode="NZ">
<Name xml:lang="en">Branch Location</Name>
<PostalAddress>
<DeliverTo>Mike Brady</DeliverTo>
<Street>456 Something Drive</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</ShipTo>The Address addressID attribute is a unique identifier for the ShipTo location in Unimarket. This can be useful when mapping this to an account or delivery location within the suppliers system.
The Name element is the name assigned to the location.
The PostalAddress element includes multiple elements relating to the address.
The DeliverTo element will show the Attention field value selected during checkout. By default this is the Buyers name.
The Street element can be repeated up to 3 times and contains information about the street address.
The City element contains the city.
The State element contains the state or region.
The PostalCode element contains the post or zip code.
The Country element contains the country and the isoCountryCode attribute is the ISO country code.
The Email element contains the email address for the Buyer.
BillTo
This BillTo element contains address information on the billing address for the order.
<BillTo>
<Address addressID="001" isoCountryCode="NZ">
<Name xml:lang="en">Head Office</Name>
<PostalAddress>
<Street>123 Something Street</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</BillTo>The Address addressID attribute is a unique identifier for the BillTo location in Unimarket.
The Name element is the name assigned to the location.
The PostalAddress element includes multiple elements relating to the address.
The Street element can be repeated up to 3 times and contains information about the street address.
The City element contains the city.
The State element contains the state or region.
The PostalCode element contains the post or zip code.
The Country element contains the country and the isoCountryCode attribute is the ISO country code.
The Email element contains the email address for the Buyer.
Shipping
This is the header level Shipping amount. The element will be included even when there is no charge.
<Shipping>
<Money currency="NZD">0.00</Money>
<Description xml:lang="en">Standard Delivery</Description>
</Shipping>
Tax
This is the summary Tax information for the orders, including the break down of the shippingTax and the tax for the lines.
<Tax>
<Money currency="NZD">0.75</Money>
<Description xml:lang="en">NZ GST</Description>
<TaxDetail category="GST" percentageRate="15.00" purpose="shippingTax">
<TaxableAmount>
<Money currency="NZD">0.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.00</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">5.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.75</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
</Tax>The TaxDetail element contains the category, percentageRate and purpose attributes along with the TaxableAmount and TaxAmount elements.
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">5.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.75</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>The category attribute is the type of tax that is being applied.
The percentageRate attribute is the tax rate being applied.
The purpose attribute indicates which part of the order is included in the tax calculation.
The TaxableAmount element is the subtotal amount excluding tax.
The TaxAmount element is the amount of tax for the TaxableAmount.
Note: There is a TaxDetail element for each purpose.
Contact
This contains the Name and Email Address for the Buyer.
<Contact role="buyer">
<Name xml:lang="en">Mike Brady</Name>
<Email>mike.brady@unimarket.com</Email>
</Contact>
Extrinsics
Extrinsics are additional elements that can be included to extend the cXML standard.
This is where you can find additional information about the order.
<Extrinsic name="buyer-credential">
<Credential domain="unimarket-user">
<Identity>mike.brady@unimarket.com</Identity>
</Credential>
</Extrinsic>
<Extrinsic name="shippingNote"/>
<Extrinsic name="requisition-created-date">2020-11-16T12:17:51.055+13:00</Extrinsic>
<Extrinsic name="organisation">Mike Test Environment</Extrinsic>
<Extrinsic name="organisation-unit-ref-code">Testing</Extrinsic>
<Extrinsic name="is-retrofit-order">no</Extrinsic>
<Extrinsic name="order-source-type">DEFAULT</Extrinsic>
<Extrinsic name="requisition-source-type">DEFAULT</Extrinsic>
ItemOut
The ItemOut element is repeated for each item that is included in the order.
<ItemOut lineNumber="1" quantity="1">
<ItemID>
<SupplierPartID>1010003</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10003</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10003</ManufacturerName>
</ItemDetail>
<SupplierID domain="external-id">TestVendorID</SupplierID>
<ShipTo>...</ShipTo>
<Shipping>...</Shipping>
<Tax>...</Tax>
<Comments/>
</ItemOut>The ItemOut lineNumber attribute is the line number for that item on the order.
The ItemOut quantity attribute is the quantity ordered for the item.
<ItemOut lineNumber="1" quantity="1">
ItemID
This includes identifying codes for the item.
<ItemID>
<SupplierPartID>1010003</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>The SupplierPartID element is the product/item/SKU code for the item.
The SupplierPartAuxiliaryID element is a supporting code used in conjunction with the SupplierPartID. This is typically used for configuration details for a variable items.
ItemDetail
This includes more descriptive elements about the item.
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10003</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10003</ManufacturerName>
</ItemDetail>The UnitPrice element is the price per unit excluding tax for the item.
The Description element is the name for the item.
The UnitOfMeasure element is the in which the unit is measured for the item.
The Classification element is the UNSPSC for the item. This is derived from the catalogue when the item is selected, from the default category for the supplier set by the customer or blank if it's not supplied.
<Classification domain="UNSPSC">44000000</Classification>
The ManufacturerName element the item description of the item along with any form details.
SupplierID
The SupplierID element will contain the Supplier ID assigned by the customer or when this is not assigned; it will default to the unique ID generated by Unimarket for the supplier.
external-id:
<SupplierID domain="external-id">TestVendorID</SupplierID>
unimarket-code:
<SupplierID domain="unimarket-code">[Unique Supplier UUID]</SupplierID>
ShipTo
This ShipTo element contains address information on where the customer would like the order to be delivered.
<ShipTo>
<Address addressID="101" isoCountryCode="NZ">
<Name xml:lang="en">Branch Location</Name>
<PostalAddress>
<DeliverTo>Mike Brady</DeliverTo>
<Street>456 Something Drive</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</ShipTo>The Address addressID attribute is a unique identifier for the ShipTo location in Unimarket. This can be useful when mapping this to an account or delivery location within the suppliers system.
The Name element is the name assigned to the location.
The PostalAddress element includes multiple elements relating to the address.
The DeliverTo element will show the Attention field value selected during checkout. By default this is the Buyers name.
The Street element can be repeated up to 3 times and contains information about the street address.
The City element contains the city.
The State element contains the state or region.
The PostalCode element contains the post or zip code.
The Country element contains the country and the isoCountryCode attribute is the ISO country code.
The Email element contains the email address for the Buyer.
Note: This is the same detail that appears in the OrderRequestHeader element. Some systems might need this information at item level.
Shipping
This is the item level Shipping amount. The element will be included even when there is no charge.
<Shipping>
<Money currency="NZD">0.00</Money>
<Description xml:lang="en">Standard Delivery</Description>
</Shipping>
Tax
This is the Tax information for the item.
<Tax>
<Money currency="NZD">0.15</Money>
<Description xml:lang="en">NZ GST</Description>
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">1.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.15</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
</Tax>The Money element total amount of tax for the item.
The Description element is the description of the tax being applied.
The category attribute is the type of tax that is being applied.
The percentageRate attribute is the tax rate being applied.
The purpose attribute indicates which part of the order is included in the tax calculation. For items on the order this will be "tax".
The TaxableAmount element is the subtotal amount excluding tax for the item.
The TaxAmount element is the amount of tax for the TaxableAmount.
Note: There is a TaxDetail element for each purpose.
Comments
The Comments element is where any item level notes are included.
<Comments>For Mike</Comments>
Complete Basic Order Example
<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="dc61a74d-82ac-4a87-8b83-6e757edd7f85" timestamp="2020-11-16T12:17:51.945+13:00" version="1.2.021" xml:lang="en">
<Header>
<From>
<Credential domain="DUNS">
<Identity>CUSTOMER IDENTIFIER</Identity>
</Credential>
</From>
<To>
<Credential domain="DUNS">
<Identity>SUPPLIER IDENTIFIER</Identity>
</Credential>
</To>
<Sender>
<Credential domain="DUNS">
<Identity>CUSTOMER/SYSTEM IDENTIFIER</Identity>
<SharedSecret>SHAREDSECRET</SharedSecret>
</Credential>
<UserAgent>unimarket</UserAgent>
</Sender>
</Header>
<Request deploymentMode="test">
<OrderRequest>
<OrderRequestHeader orderDate="2020-11-16T12:17:51.124+13:00" orderID="102" orderType="regular" type="new">
<Total>
<Money currency="NZD">5.75</Money>
</Total>
<ShipTo>
<Address addressID="101" isoCountryCode="NZ">
<Name xml:lang="en">Branch Location</Name>
<PostalAddress>
<DeliverTo>Mike Brady</DeliverTo>
<Street>456 Something Drive</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</ShipTo>
<BillTo>
<Address addressID="001" isoCountryCode="NZ">
<Name xml:lang="en">Head Office</Name>
<PostalAddress>
<Street>123 Something Street</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</BillTo>
<Shipping>
<Money currency="NZD">0.00</Money>
<Description xml:lang="en">Standard Delivery</Description>
</Shipping>
<Tax>
<Money currency="NZD">0.75</Money>
<Description xml:lang="en">NZ GST</Description>
<TaxDetail category="GST" percentageRate="15.00" purpose="shippingTax">
<TaxableAmount>
<Money currency="NZD">0.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.00</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">5.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.75</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
</Tax>
<Contact role="buyer">
<Name xml:lang="en">Mike Brady</Name>
<Email>mike.brady@unimarket.com</Email>
</Contact>
<Extrinsic name="buyer-credential">
<Credential domain="unimarket-user">
<Identity>mike.brady@unimarket.com</Identity>
</Credential>
</Extrinsic>
<Extrinsic name="shippingNote"/>
<Extrinsic name="requisition-created-date">2020-11-16T12:17:51.055+13:00</Extrinsic>
<Extrinsic name="organisation">Mike Test Environment</Extrinsic>
<Extrinsic name="organisation-unit-ref-code">Testing</Extrinsic>
<Extrinsic name="is-retrofit-order">no</Extrinsic>
<Extrinsic name="order-source-type">DEFAULT</Extrinsic>
<Extrinsic name="requisition-source-type">DEFAULT</Extrinsic>
</OrderRequestHeader>
<ItemOut lineNumber="1" quantity="1">
<ItemID>
<SupplierPartID>1010003</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10003</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10003</ManufacturerName>
</ItemDetail>
<SupplierID domain="external-id">TestVendorID</SupplierID>
<ShipTo>
<Address addressID="101" isoCountryCode="NZ">
<Name xml:lang="en">Branch Location</Name>
<PostalAddress>
<DeliverTo>Mike Brady</DeliverTo>
<Street>456 Something Drive</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</ShipTo>
<Shipping>
<Money currency="NZD">0.00</Money>
<Description xml:lang="en"/>
</Shipping>
<Tax>
<Money currency="NZD">0.15</Money>
<Description xml:lang="en">NZ GST</Description>
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">1.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.15</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
</Tax>
<Comments>For Mike</Comments>
</ItemOut>
<ItemOut lineNumber="2" quantity="4">
<ItemID>
<SupplierPartID>1010004</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10004</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10004</ManufacturerName>
</ItemDetail>
<SupplierID domain="external-id">TestVendorID</SupplierID>
<ShipTo>
<Address addressID="101" isoCountryCode="NZ">
<Name xml:lang="en">Branch Location</Name>
<PostalAddress>
<DeliverTo>Mike Brady</DeliverTo>
<Street>456 Something Drive</Street>
<City>Auckland</City>
<State/>
<PostalCode>1010</PostalCode>
<Country isoCountryCode="NZ">New Zealand</Country>
</PostalAddress>
<Email>mike.brady@unimarket.com</Email>
</Address>
</ShipTo>
<Shipping>
<Money currency="NZD">0.00</Money>
<Description xml:lang="en"/>
</Shipping>
<Tax>
<Money currency="NZD">0.60</Money>
<Description xml:lang="en">NZ GST</Description>
<TaxDetail category="GST" percentageRate="15.00" purpose="tax">
<TaxableAmount>
<Money currency="NZD">4.00</Money>
</TaxableAmount>
<TaxAmount>
<Money currency="NZD">0.60</Money>
</TaxAmount>
<Description xml:lang="en">NZ GST</Description>
</TaxDetail>
</Tax>
<Comments/>
</ItemOut>
</OrderRequest>
</Request>
</cXML>
Expected Response
The expected response back to the POST request is a cXML payload with a 200 Status code.
<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="1707252931182" timestamp="2024-02-06T20:55:31+00:00" xml:lang="en-US">
<Response>
<Status code="200" text="OK">Purchase Order Processed Successfully</Status>
</Response>
</cXML>The Status code attribute should be in the 200 range. All others codes will be considered an error.
The Status element can include any information about the order.
Exchange Rates
When an order is sent from your customer it will use the currency as per the supplier store. There are additional attributes included in each Money element to show the value in the currency set for the customer.
The OrderRequestHeader element contains an additional Extrinsic element showing the exchange rate.
<Extrinsic name="exchange-rate">
<ExchangeRate alternate-currency="NZD" currency="USD" user-specified="false">0.6930</ExchangeRate>
</Extrinsic>The ItemOut element also shows the exchange rate in the attributes for the Money elements in UnitPrice and Shipping.
<ItemOut lineNumber="1" quantity="5">
<ItemID>
<SupplierPartID>1000010</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money alternateAmount="1.443001" alternateCurrency="NZD" currency="USD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10</ManufacturerName>
</ItemDetail>
<SupplierID domain="external-id">2</SupplierID>
<ShipTo>...</ShipTo>
<Shipping>
<Money alternateAmount="0.00" alternateCurrency="NZD" currency="USD">0.00</Money>
<Description xml:lang="en"/>
</Shipping>
<Tax>...</Tax>
<Comments/>
</ItemOut>The alternateCurrency attribute shows the currency code that is set for the customer.
The alternateAmount attribute shows the value in the currency set for the customer.
Note: More information on how exchange rates are managed is available here: Exchange Rates
Distributions
Distributions allow the customer to code their purchases to account codes. These can be included at an item level in the purchase order.
<Distribution>
<Accounting name="GLCode">
<AccountingSegment id="Auckland">
<Name xml:lang="en">Location</Name>
<Description xml:lang="en">Auckland Office</Description>
</AccountingSegment>
<AccountingSegment id="Blue">
<Name xml:lang="en">Team</Name>
<Description xml:lang="en">Team Blue</Description>
</AccountingSegment>
</Accounting>
<Charge>
<Money currency="NZD">12.00</Money>
</Charge>
</Distribution>The Distribution element contains Accounting and Charge elements. This is repeated for each account code used for the iteam.
The Accounting name attribute shows the account coding format that was used.
The AccountingSegment element is repeated for each part of the account code.
The AccountingSegment id attribute is the value for the account code part.
The Name element is the name of the account code part.
The Description element is the description of the value in the AccountingSegment id attribute.
The Charge element contains the value that has been assigned to the account code.
Example Distribution for an Item
This show an two account codes for the same line. The account code consists of two parts: Location and Team.
<ItemOut lineNumber="1" quantity="15">
<ItemID>
<SupplierPartID>1010005</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10005</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10005</ManufacturerName>
</ItemDetail>
<SupplierID domain="external-id">TestVendorID</SupplierID>
<ShipTo>...</ShipTo>
<Shipping>...</Shipping>
<Tax>...</Tax>
<Distribution>
<Accounting name="GLCode">
<AccountingSegment id="Auckland">
<Name xml:lang="en">Location</Name>
<Description xml:lang="en">Auckland Office</Description>
</AccountingSegment>
<AccountingSegment id="Blue">
<Name xml:lang="en">Team</Name>
<Description xml:lang="en">Team Blue</Description>
</AccountingSegment>
</Accounting>
<Charge>
<Money currency="NZD">12.00</Money>
</Charge>
</Distribution>
<Distribution>
<Accounting name="GLCode">
<AccountingSegment id="Wellington">
<Name xml:lang="en">Location</Name>
<Description xml:lang="en">Wellington Office</Description>
</AccountingSegment>
<AccountingSegment id="Red">
<Name xml:lang="en">Team</Name>
<Description xml:lang="en">Team Red</Description>
</AccountingSegment>
</Accounting>
<Charge>
<Money currency="NZD">3.00</Money>
</Charge>
</Distribution>
<Comments/>
</ItemOut>
Distribution Extrinsics
Distribution Extrinsics can be included in the ItemDetail element to show the percentage assigned for each account code for the item.
The Extrinsic element has a name attribute of "unimarket-distribution-details" and will include repeating extrinsic elements for each account code for the item.
The account code can be identified in the Extrinsic name attribute with the format:
"Account Code Format":"Account Code"
In this example it's: "GLCode:Auckland-Blue" or "GLCode:Wellington-Red"
The associated percentage can be found in the contained Extrinsic element.
<ItemOut lineNumber="1" quantity="15">
<ItemID>
<SupplierPartID>1010005</SupplierPartID>
<SupplierPartAuxiliaryID/>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="NZD">1.00</Money>
</UnitPrice>
<Description xml:lang="en">Product Code 10005</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">44000000</Classification>
<ManufacturerName xml:lang="en">Description 10005</ManufacturerName>
<Extrinsic name="unimarket-distribution-details">
<Extrinsic name="GLCode:Auckland-Blue">
<Extrinsic name="percentage">80.00000000</Extrinsic>
</Extrinsic>
<Extrinsic name="GLCode:Wellington-Red">
<Extrinsic name="percentage">20.00000000</Extrinsic>
</Extrinsic>
</Extrinsic>
</ItemDetail>
<SupplierID domain="external-id">TestVendorID</SupplierID>
<ShipTo>...</ShipTo>
<Shipping>...</Shipping>
<Tax>...</Tax>
<Distribution>...</Distribution>
<Distribution>...</Distribution>
<Comments/>
</ItemOut>
Common cXML Elements
The tables show some examples on where to find common fields used from the Header and Item levels.
Header Level
Detail Path Example Customer cXML/Header/From/Credential[@domain="DUNS"]/Identity CUSTOMER IDENTIFIER Environment cXML/Request/@deploymentMode test Order Date cXML/Request/OrderRequest/OrderRequestHeader/@orderDate 2020-11-16T12:17:51.124+13:00 Order Number cXML/Request/OrderRequest/OrderRequestHeader/@orderID 102 Order Status cXML/Request/OrderRequest/OrderRequestHeader/@type new Ship To ID cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/@addressID 101 Ship To Name cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/Name Branch Location Deliver To / Attn To cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/DeliverTo Mike Brady Street cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/Street[1]
cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/Street[2]
cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/Street[3]
456 Something Drive City cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/City Auckland State / Region cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/State Post / ZIP Code cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/PostalCode 1010 Country cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/Country New Zealand Buyer Name cXML/Request/OrderRequest/OrderRequestHeader/Contact[@role="buyer"]/Name Mike Brady Buyer Email cXML/Request/OrderRequest/OrderRequestHeader/Contact[@role="buyer"]/Email mike.brady@unimarket.com Order Total cXML/Request/OrderRequest/OrderRequestHeader/Total/Money 5.75 Shipping Total cXML/Request/OrderRequest/OrderRequestHeader/Shipping/Money 0.00 Tax Total cXML/Request/OrderRequest/OrderRequestHeader/Tax/Money 0.75 Order Note cXML/Request/OrderRequest/OrderRequestHeader/Extrinsic[@name="shippingNote"] Item Level
Detail Path Example Line Number cXML/Request/OrderRequest/ItemOut[*]/@lineNumber 1 Quantity cXML/Request/OrderRequest/ItemOut[*]/@quantity 1 Item Code cXML/Request/OrderRequest/ItemOut[*]/ItemID/SupplierPartID 1010003 Item Description cXML/Request/OrderRequest/ItemOut[*]/ItemDetail/Description Product Code 10003 Unit of Measure cXML/Request/OrderRequest/ItemOut[*]/ItemDetail/UnitOfMeasure EA UNSPSC / Product Category cXML/Request/OrderRequest/ItemOut[*]/ItemDetail/Classification 44000000 Unit Price cXML/Request/OrderRequest/ItemOut[*]/ItemDetail/UnitPrice/Money 1.00 Tax cXML/Request/OrderRequest/ItemOut[*]/Tax/Money 0.15 Item Note cXML/Request/OrderRequest/ItemOut[*]/Comments For Mike
Additional Information
Example Downloadable Files