Summary
This document outlines the technical specifications for the Unimarket Purchase Order (PO) Integration using the cXML standard. POs are sent via an HTTPS endpoint using the POST method, with the cXML payload secured, ideally, by TLS 1.2.
Basic Purchase Order Structure
A basic PO begins with a <Header> for authentication and identification, followed by a <Request> containing the <OrderRequest> and repeating <ItemOut> elements for each ordered item.
Example Basic Purchase Order:
<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="[A Unique Value]" timestamp="..." version="1.2.021" xml:lang="en">
<Header>...</Header>
<Request deploymentMode="test">
<OrderRequest>
<OrderRequestHeader orderDate="..." orderID="102" orderType="regular" type="new">
<Total>...</Total>
<ShipTo>...</ShipTo>
<BillTo>...</BillTo>
<Shipping>...</Shipping>
<Tax>...</Tax>
<Contact role="buyer">...</Contact>
<Extrinsic name="buyer-credential">...</Extrinsic>
</OrderRequestHeader>
<ItemOut lineNumber="1" quantity="1" requisitionID="56">...</ItemOut>
<ItemOut lineNumber="2" quantity="4" requisitionID="56">...</ItemOut>
</OrderRequest>
</Request>
</cXML>
Header and Request
Header (Authentication and Identification)
The <Header> is used to authenticate the message using the <SharedSecret> and identify the sender/recipient.
| Element | Purpose | Required Attributes/Elements |
|---|---|---|
<From> |
Identifies the Customer sending the order. |
<Credential domain="DUNS"> and <Identity> (Customer Identifier).
|
<To> |
Identifies the Supplier receiving the order. |
<Credential domain="DUNS"> and <Identity> (Supplier Identifier).
|
<Sender> |
Identifies the sending system (Unimarket/Customer System) for authentication. |
<Identity> (Customer/System Identifier) and <SharedSecret>.
|
Request and Deployment Mode
The <Request> element indicates the environment:
Test:
<Request deploymentMode="test">-
Production:
<Request deploymentMode="production">
Order Request Header Details
The <OrderRequestHeader> provides global details about the PO.
| Attribute/Element | Purpose | Key Values |
|---|---|---|
orderDate |
Date and time the order was generated (Format: YYYY-MM-DD'T'hh:mm:ss.SSSZ).
|
|
orderID |
The Purchase Order number. | |
orderType |
Type of order. |
regular or blanket.
|
type |
Status of the order. |
new, update (includes orderVersion attribute), or delete (cancelled order).
|
<Total> |
Total value of all items, including taxes. |
Contains <Money currency="[CODE]">.
|
<ShipTo> |
Delivery address for the order. |
Includes <Address addressID> (unique identifier), <DeliverTo> (Buyer name), and full address details.
|
<BillTo> |
Billing address for the order. |
Includes <Address addressID> and full address details.
|
<Shipping> |
Header level shipping amount. |
Contains <Money> (even if zero).
|
<Tax> |
Summary tax information. |
Includes repeating <TaxDetail> elements for purpose="shippingTax" and purpose="tax".
|
<Contact role="buyer"> |
Buyer's name and email address. | |
<Extrinsic> |
Additional order information. |
Used for buyer-credential, shippingNote, requisition-created-date, organisation, etc.
|
4. Item Out Details (Line Items)
The <ItemOut> element is repeated for each item on the order and contains item-specific details, including item-level address, shipping, and tax (which duplicates header-level information for systems that require it).
| Element/Attribute | Purpose | Key Contained Elements |
|---|---|---|
lineNumber |
The item's line number on the order. | |
quantity |
The quantity ordered for the item. | |
<ItemID> |
Identifiers for the product. |
<SupplierPartID> (product/item/SKU code) and <SupplierPartAuxiliaryID>.
|
<ItemDetail> |
Descriptive elements about the item. |
<UnitPrice> (excluding tax), <Description>, <UnitOfMeasure> (e.g., EA), <Classification domain="UNSPSC">.
|
<SupplierID> |
Supplier ID assigned by the customer or Unimarket's unique ID. |
domain="external-id" or domain="unimarket-code".
|
<ShipTo> |
Item-level ShipTo address. |
Same structure as the header-level <ShipTo>.
|
<Shipping> |
Item-level shipping amount. |
Contains <Money> (even if zero).
|
<Tax> |
Item-level tax information. |
Contains <TaxDetail category="..." purpose="tax">.
|
<Comments> |
Any item-level notes. |
Exchange Rates (If Applicable)
If the supplier store's currency differs from the customer's currency, exchange rate details are included:
Header Level: An
<Extrinsic name="exchange-rate">containing the<ExchangeRate>is included in the<OrderRequestHeader>.Item Level:
<Money>elements within<UnitPrice>and<Shipping>includealternateCurrencyandalternateAmountattributes to show the value in the customer's currency.
Distributions (Accounting)
Distributions allow purchases to be coded to account codes at the item level.
-
<Distribution>: Contains<Accounting>and<Charge>elements.<Accounting>is repeated for each part of the account code (e.g., Location, Team).<Charge>shows the monetary value assigned to that account code.
Distribution Extrinsics: Included in the
<ItemDetail>element withname="unimarket-distribution-details". These show the percentage assigned for each account code. The account code is identified in the<Extrinsic name="Account Code Format:Account Code">(e.g.,GLCode:Auckland-Blue).
5. Expected Response
The supplier's system must send back a cXML payload in response to the POST request.
The expected response is a cXML payload containing a 200 Status code.
<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="..." timestamp="..." xml:lang="en-US">
<Response>
<Status code="200" text="OK">Purchase Order Processed Successfully</Status>
</Response>
</cXML>
The
Status codeattribute must be in the 200 range (other codes are considered errors).
6. Common cXML Elements Mapping
Header Level
| Detail | cXML 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 |
| Buyer Name | cXML/Request/OrderRequest/OrderRequestHeader/Contact[@role="buyer"]/Name |
Mike Brady |
| Order Total | cXML/Request/OrderRequest/OrderRequestHeader/Total/Money |
5.75 |
| Shipping Total | cXML/Request/OrderRequest/OrderRequestHeader/Shipping/Money |
0.00 |
Item Level
| Detail | cXML 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 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 |