Purchase Order (OrderRequest) Technical Documentation

  • Updated

This document defines the transport layer requirements for integrating Purchase Orders from Unimarket into a Community's receiving system (ERP/Financial System). Unimarket utilizes the industry-standard cXML protocol delivered over a secure web connection.

 

Transmission Overview

Purchase Orders are pushed from Unimarket to the community's designated endpoint in real-time upon approval.

Component Requirement
Protocol cXML (Commerce eXtensible Markup Language)
Transport HTTP(S)
Method POST
Security TLS 1.2 or higher

Security & Encryption

TLS 1.2 Requirements

To maintain the highest level of data integrity and confidentiality, all connections must be secured using TLS 1.2 (Transport Layer Security) or higher. Unimarket ideally requires this version to mitigate vulnerabilities associated with older SSL and TLS versions.

 

Endpoint Authentication

In addition to the transport-level security (HTTPS), the message itself is authenticated using the credentials provided in the cXML <Header>:

  • Identity/SharedSecret: The receiving system should validate the SharedSecret provided in the XML against a pre-configured key to ensure the request originated from a trusted Unimarket environment.

 

Communication Logic (POST Request)

The integration follows a standard request-response pattern:

  1. Initiation: Unimarket initiates a connection to the community's publicly accessible (or VPN-secured) HTTPS URL.
  2. Payload: The cXML OrderRequest is sent in the body of an HTTP POST request.
  3. Content-Type: The request is typically sent with Content-Type: text/xml or application/xml.
  4. Acknowledgment: The receiving system must process the XML and return a synchronous cXML Response (with a 200 status code), within the same connection session to signal a successful handshake.

 

In this Article

Example Basic Purchase Order

Header

Request

OrderRequest

 - Total

 - ShipTo

 - BillTo

 - Shipping

 - Tax

 - Tax Detail

 - Contact

 - Extrinsics

ItemOut

 - ItemID

 - ItemDetail

 - SupplierID

 - Comments

Complete Basic Order Example

Expected Response

Exchange Rates

Distributions

Distribution Extrinsics

Common cXML Elements

What's Next/Related

 

 

Example Basic Purchase Order

The template illustrates how the header, request logic, and financial elements discussed previously come together in a standard procurement message sent from Unimarket to a supplier.

<?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>

 

Key Components of this Example:

  • Root cXML Attributes: Includes a unique payloadID and a timestamp which are essential for message tracking and preventing duplicate processing.

  • The Header Block: Identifies the sending institution and the target supplier. It also includes the SharedSecret, which is the primary authentication method for cXML.

  • Deployment Mode: Set to production in this example, signalling a live business transaction.

  • Three-Way Match Support: Includes ShipTo, BillTo, and ItemOut details (SKUs, quantities, and prices) necessary for the supplier to fulfill the order and eventually send a matching invoice.

  • Tax Logic: The ItemOut has a line-level tax amount, which results in the header Total.

 

 

Header

The <Header> element is the first major block in a cXML document. Its primary purpose is to provide routing information and credentials to authenticate the message between the sender (Unimarket/Community) and the receiver (Supplier).

<Header>
    <From>
        <Credential domain="">
            <Identity/>
        </Credential>
    </From>
    <To>
        <Credential domain="">
            <Identity/>
        </Credential>
    </To>
    <Sender>
        <Credential domain="">
            <Identity/>
            <SharedSecret/>
        </Credential>
        <UserAgent>unimarket</UserAgent>
    </Sender>
</Header>

 

Header Structure

A standard cXML header contains three main components:

  • From: The identity of the organization where the request originates.
  • To: The identity of the organization to which the request is destined.
  • Sender: The identity of the entity sending the message (including the SharedSecret used for authentication).

Community "Empty Header" Behavior

In many Unimarket community configurations, the <Header> sub-elements are intentionally left empty or use placeholder values. This typically occurs when:

  • Gateway Authentication: Authentication is handled by a dedicated integration gateway rather than on a per-message basis within the XML.
  • System-to-System Trust: The supplier and the community have an established secure tunnel (like an IP-whitelisted connection) that removes the need for credential-heavy headers.

Implementation Logic

If your system is receiving orders from a community with empty headers, your integration logic should:

  1. Skip Identity Verification: Bypass logic that requires specific values in the <From> or <To> blocks.
  2. Focus on the Payload: Shift focus to the <OrderRequestHeader> inside the <Request> block, which contains the actual Purchase Order details (PO Number, Date, etc.).
  3. Alternative Authentication: Ensure your firewall or API gateway is managing security if the XML itself is not providing a SharedSecret.

 

 

Request

The Request element serves as the top-level envelope for the OrderRequest payload. Its primary function is to define the operational context of the message, specifically identifying whether the data originated from a Test (Demo) or Production environment.

Below are representations of how the Request element wraps the OrderRequest and identifies the environment:

Test:

<Request deploymentMode="test">

Production:

<Request deploymentMode="production">

 

The <Request> Element

This element wraps the specific business transaction (in this case, the OrderRequest). By inspecting the attributes of this element, receiving systems can determine how to handle the incoming data.

Environment Identification

The environment status is typically defined by the deploymentMode attribute within the Request tag.

Attribute Value Environment Description
test Demo / UAT Indicates the order was generated in a sandbox or test environment. No physical goods should be shipped, and no financial liability is created.
production Live Indicates a legitimate business transaction from the live production environment. These orders require standard fulfillment and payment processing.

 

 

OrderRequest

These attributes are critical for mapping purchase order data to external supplier systems or internal ERPs.

<OrderRequestHeader orderDate="2020-11-16T12:17:51.124+13:00" orderID="102" orderType="regular" type="new">

 

Primary Order Attributes

Attribute Description Data Format / Example
orderDate The timestamp when the order was generated in the Unimarket system. YYYY-MM-DD'T'hh:mm:ss.SSSZ
orderID The unique identifier for the Purchase Order (PO Number). e.g., PO100052
orderType The classification of the procurement agreement. regular or blanket

 

Order Lifecycle Status (type)

The type attribute defines the action required by the receiving system. The behavior of the XML payload changes depending on this status.

Status: new

  • Definition: Represents a brand-new Purchase Order.
  • Action: The receiving system should create a new record.

Status: update

  • Definition: Indicates that an existing order has been modified (e.g., via a Change Order).
  • Payload Changes: When the status is update, two additional attributes are included to manage version control:
    • orderVersion: An integer representing the version of the order. Versions start at 2 and increment with every approved change.
    • isInternalVersion: A flag indicating if the change is intended for internal tracking only. For standard outbound orders to suppliers, this is always set to "no".
  • Action: The receiving system should overwrite the existing order details with the new data provided in the payload.

Status: delete

  • Definition: Indicates that the Purchase Order has been cancelled.
  • Action: The receiving system should mark the order as cancelled or void.

 

 

Total

These elements are used to communicate the total monetary value of a Purchase Order, including all applicable taxes and currency identifiers.

Below is a representation of how these elements appear within an outbound OrderRequest XML:

<total>
    <Money currency="USD">1250.75</Money>
</total>

 

The <total> Element

The total element serves as the parent container for the order's financial summary. It encapsulates the overall value of the procurement request.

The <Money> Element

Contained within the total element, the Money element is the data carrier for the actual numerical value.

  • Definition: Represents the total aggregate value of all line items included in the order.
  • Tax Logic: The value displayed in the Money element is the Gross Total, meaning it includes all applicable taxes (e.g., GST, VAT, or Sales Tax).
  • Attributes:
    • currency: This mandatory attribute specifies the 3-letter ISO 4217 currency code (e.g., USD, NZD, AUD, GBP) associated with the transaction.

 

 

ShipTo

The <ShipTo> element is a critical component of the OrderRequestHeader. It provides the supplier with the precise physical location for delivery and the specific "Attention To" details required for successful receipt of goods within the community.

<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>

 

Element Structure

The ShipTo element follows a hierarchical structure to separate location names from physical postal data.

XML Tag Description Business Context
<Address> The parent container for the shipping site. Often includes an addressID attribute matching the community's internal location code.
<Name> The descriptive name of the delivery site. e.g., "North Campus Receiving" or "Engineering Lab."
<DeliverTo> The specific person or department. This is the "Attention To" field used to route the package once it arrives on site.
<Street> The physical street address. Can include multiple lines if needed for complex campus layouts.
<City> The city or town. The primary municipality for delivery.
<State> The state, province, or region. Usually provided as a 2-3 letter code (e.g., TX, NSW, AKL).
<PostalCode> The Zip or Postcode. Critical for carrier routing.
<Country> The country name and code. Includes the isoCountryCode attribute (e.g., US, NZ, AU).

Integration & 3-Way Match

The information in the ShipTo element is the benchmark for the Receiving process:

  • Receiving Verification: When a user performs "Desktop Receiving" in Unimarket, they verify that the goods arrived at the location specified in this element.
  • Carrier Accuracy: Suppliers should ensure that the DeliverTo information is clearly printed on the shipping label to prevent packages from being "lost" at central receiving docks.

Note: This is the same detail that appears in the OrderRequestHeader element. Some systems might need this information at item level.

 

 

BillTo

The <BillTo> element within the OrderRequestHeader defines the legal and financial entity responsible for paying the invoice. This information is used by suppliers to ensure that their invoices are addressed correctly for tax and audit purposes.

<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>

 

Element Structure

The BillTo element uses the standard cXML <Address> structure. While it looks similar to the ShipTo block, its purpose is purely financial.

XML Tag Description Business Context
<Address> Container for the billing entity. Often includes an addressID used for internal AP routing.
<Name> The name of the billing department. Typically "Accounts Payable" or "Financial Services."
<Street> The billing street or PO Box. Many institutions use a centralized PO Box for all invoices.
<City> The billing city. The municipality where the AP office is located.
<State> The state or province. Provided as a standard code (e.g., TX, NSW, AKL).
<PostalCode> Zip or Postcode. Used for mailing physical invoices if electronic ones aren't available.
<Country> Country identifier. Includes the isoCountryCode (e.g., US, NZ, AU).

Importance in the Invoicing Lifecycle

The BillTo information is the foundation for the Invoice Match:

  • Tax Compliance: Suppliers must use the address in this element as the "Bill To" party on their tax invoice to comply with regional tax laws (e.g., IRD or IRS requirements).
  • AP Routing: If the community has multiple billing centers, the addressID attribute helps the supplier's system route the invoice to the correct branch in their accounts receivable ledger.
  • eInvoicing: Even when a supplier sends an electronic invoice (XML) back to Unimarket, the system validates the billing details against the original PO's BillTo block.

 

 

Shipping

The <Shipping> element within the OrderRequestHeader specifies the total freight or delivery charges for the entire Purchase Order. In the Unimarket cXML schema, this element is a standard component of the financial summary.

<Shipping>
    <Money currency="NZD">0.00</Money>
    <Description xml:lang="en">Standard Delivery</Description>
</Shipping>

 

Element Structure

The Shipping element contains a nested Money element and an optional description of the shipping method.

XML Tag Description Business Context
<Shipping> The parent container for header-level freight. Aggregates shipping for all line items.
<Money> The numerical value of the shipping charge. Must include the currency attribute (e.g., USD).
<Description> The shipping method or service level. e.g., "Ground", "Next Day Air", or "Standard Freight".

Zero-Charge Persistence

A key requirement of this integration is that the <Shipping> element is mandatory.

  • Zero Values: If the order qualifies for free shipping or the freight is included in the item prices, the element will still be present with a value of 0.00.
  • Reasoning: This consistency allows receiving systems (like a supplier's ERP) to always find the element in the same XML path, simplifying the parsing logic and preventing "null pointer" errors during ingestion.

 

 

Tax

The <Tax> element within the OrderRequestHeader provides a high-level summary of all taxes associated with the Purchase Order. To support granular financial reconciliation, this element includes a breakdown of taxes applied to individual line items versus taxes applied to shipping and freight charges.

<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>

 

 

Element Structure

The header-level Tax element serves as a container for the aggregate tax amount and a series of TaxDetail elements that categorize the tax.

XML Tag Description Business Context
<Tax> The parent container for order-level tax summary. Aggregates all tax components for the PO.
<Money> The total combined tax value. Must include the currency attribute (e.g., USD).
<Description> High-level tax summary description. e.g., "Total Order Tax".
<TaxDetail> A sub-element providing a specific breakdown. Used to separate line tax from shipping tax.

Tax Breakdown Logic

Unimarket utilizes the <TaxDetail> structure to provide the required breakdown for your financial systems:

  • Line Tax: This represents the sum of all tax amounts calculated for the physical goods or services across all ItemOut blocks.
  • Shipping Tax: This represents the tax specifically applied to the header-level shipping amount.

By providing these as distinct TaxDetail entries, receiving systems can accurately map tax expenses to the correct GL (General Ledger) codes for "Goods Tax" vs. "Freight Tax."

 

TaxDetail

The <TaxDetail> element is a child of the header-level <Tax> block. It provides a granular breakdown of how a specific tax amount was calculated, identifying the rate applied, the base amount subject to tax, and the intended purpose of the tax.

Note: There is a TaxDetail element for each purpose.

<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>

 

Attributes Reference

The TaxDetail tag includes three critical attributes that define the context of the tax calculation:

Attribute Description Typical Values
category Defines the classification of the tax. sales, vat, gst, use, service.
percentageRate The numerical tax rate expressed as a percentage or decimal. 8.25, 15, 5.0.
purpose Describes the role of this tax detail within the order. tax for lines, tax for shipping.

Child Elements

Within the TaxDetail block, two elements define the monetary values involved in the calculation:

<TaxableAmount>

  • Definition: The net amount of the order (or sub-component) that is subject to tax.
  • Calculation: This is the base value used before the percentageRate is applied.
  • Money Element: Contains a <Money> child with the appropriate currency attribute.

<TaxAmount>

  • Definition: The resulting tax value calculated by applying the rate to the taxable amount.
  • Money Element: Contains a <Money> child with the appropriate currency attribute.

 

 

Contact

The <Contact> element within the OrderRequestHeader identifies the specific individual who initiated the procurement request. This information is essential for suppliers to manage communication regarding order status, substitutions, or delivery delays.

<Contact role="buyer">
    <Name xml:lang="en">Mike Brady</Name>
    <Email>mike.brady@unimarket.com</Email>
</Contact>

 

The <Contact> element within the OrderRequestHeader identifies the specific individual who initiated the procurement request. This information is essential for suppliers to manage communication regarding order status, substitutions, or delivery delays.

Element Structure

The Contact element captures the buyer's identity and primary communication channel.

XML Tag Description Business Context
<Contact> The parent container for the buyer's info. Always includes the role="buyer" attribute.
<Name> The full name of the buyer. The person who created the requisition in Unimarket.
<Email> The buyer's email address. The primary channel for automated or manual order updates.

Role in the Procurement Lifecycle

  • Order Clarification: If a supplier has questions about a specific line item or SKU, the details in this element provide the correct person to contact.
  • Notification Routing: Many supplier systems use the email address provided in this block to send automated Advance Shipping Notices (ASN) or Order Confirmations.
  • Accountability: The Name provides a clear audit trail of who is responsible for the purchase within the community.

 

 

Extrinsics

The <Extrinsic> element is a versatile tool used to extend the standard cXML schema. It allows Unimarket and its communities to pass custom metadata that is specific to an institution's business processes but is not covered by the core cXML specification.

<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">Testing</Extrinsic>
<Extrinsic name="is-retrofit-order">no</Extrinsic>
<Extrinsic name="order-source-type">DEFAULT</Extrinsic>
<Extrinsic name="requisition-source-type">DEFAULT</Extrinsic>

 

Structure and Attributes

An Extrinsic is a simple name-value pair. It is typically found within the OrderRequestHeader (for order-wide data) or within the ItemDetail (for line-specific data).

Attribute Description Typical Usage
name The unique identifier for the custom field. e.g., "DepartmentCode", "ProjectID".
Element Value The actual data content for that field. e.g., "DEPT-77", "PRJ-998".

Common Use Cases

In the Unimarket ecosystem, Extrinsics are frequently used to communicate:

  • Account Strings: Full GL codes or accounting segments.
  • Project Codes: Tracking identifiers for grants or capital projects.
  • Internal Routing: Specific codes used for internal warehouse or mailroom processing.
  • Supplier-Specific Data: Data that a particular supplier requires for their internal processing (e.g., "ContractNumber").

 

 

ItemOut

The <ItemOut> element is the fundamental building block for line-level data in a cXML OrderRequest. This element is repeated for every unique product or service line included in the Purchase 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>

 

Attributes Reference

The ItemOut tag includes two mandatory attributes that help identify the position and volume of the line item:

Attribute Description Business Context
quantity The numerical amount of the item being ordered. e.g., 5, 10.5 (if decimals are supported).
lineNumber The sequential index of the item within the PO. Starts at 1 and increments for each subsequent item.
requestedDeliveryDate (Optional) The date the buyer expects the item. Format: YYYY-MM-DD.

Core Child Elements

Each ItemOut block contains detailed information about the specific goods or services being procured:

  • <ItemID>: Contains the primary identifiers for the product, most notably the <SupplierPartID>.
  • <ItemDetail>: Encapsulates the descriptive metadata, including:
    • <UnitPrice>: The cost per unit (wrapped in a <Money> element).
    • <Description>: A human-readable name or detailed specification of the item.
    • <UnitOfMeasure>: The standard code for the unit (e.g., EA, BOX, HR).
    • <Classification>: Often used for UNSPSC or other commodity codes.
  • <Tax>: (Optional) Line-level tax specifically for this item.
  • <Distribution>: (Optional) Used in some configurations to pass specific accounting segments for this line.

 

 

ItemID

The <ItemID> element, located within the ItemOut block, contains the technical identifiers used to uniquely distinguish a product or service. This element is the primary "key" used by a supplier's ERP to map the incoming request to a specific inventory item.

<ItemID>
    <SupplierPartID>1010003</SupplierPartID>
    <SupplierPartAuxiliaryID/>
</ItemID>

 

Core Child Elements

The ItemID block uses standard cXML identifiers to ensure compatibility across different supply chain networks.

XML Tag Description Business Context
<SupplierPartID> The primary SKU or catalog number provided by the supplier. This is the most critical field for fulfillment. It must match the supplier's internal part number exactly.
<SupplierPartAuxiliaryID> An additional identifier used to clarify a specific part. Often used for variant identifiers (e.g., color/size codes) or internal unique IDs that aren't the primary SKU.
<BuyerPartID> The community's internal part number. Used if the institution tracks items using their own SKU system (often seen in stockroom or inventory-managed items).

 

 

ItemDetail

The <ItemDetail> element, nested within the ItemOut block, provides the descriptive and financial attributes of a line item. This metadata is used by the supplier to understand exactly what is being ordered and by the buyer's system for spend analysis and accounting.

<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>

 

Core Child Elements

The ItemDetail block encapsulates several data points required for commercial transactions:

XML Tag Description Business Context
<UnitPrice> The cost per unit of the item. Contains a <Money> element with the currency attribute.
<Description> A human-readable text string describing the item. Includes the xml:lang attribute (e.g., en).
<UnitOfMeasure> The standard code for the unit of packaging. Uses UN/CEFACT or ANSI codes (e.g., EA, CS, DZ).
<Classification> A commodity code for spend categorization. Typically uses the UNSPSC domain.
<ManufacturerPartID> The part number assigned by the manufacturer. Used when the supplier SKU is different from the OEM part number.
<ManufacturerName> The name of the product's manufacturer. Useful for clarifying brand-specific requirements.
<Extrinsic> Custom metadata extensions. Used for line-level account codes, asset tags, or project IDs.

 

 

SupplierID

The <SupplierID> element provides the definitive identification of the vendor for the transaction. This element is vital for your ERP's accounts payable module, as it allows the system to map the Unimarket order to the correct "Vendor Master" record in your internal database.

Sample external-id:

<SupplierID domain="external-id">TestVendorID</SupplierID>

Sample unimarket-code:

<SupplierID domain="unimarket-code">[Unique Supplier UUID]</SupplierID>

 

Identification Logic (Hierarchy)

Unimarket utilizes a hierarchical approach to ensure the supplier is always identifiable, even if a formal mapping has not yet been completed:

  1. Community-Assigned ID (Primary): If your institution has assigned a specific ID to the supplier within Unimarket (e.g., your ERP Vendor Number), this value will be used.
  2. Unimarket Unique ID (Fallback): If no internal ID has been assigned by the community, the system defaults to the unique, system-generated UUID provided by the Unimarket platform.

Business Context & Integration

Data Type Description Integration Benefit
Community ID Your internal ERP vendor code (e.g., VNDR-8892). Allows for "Zero-Touch" matching in your accounting system.
Unimarket ID A unique system string (e.g., 9ca1-4f2b-8e12). Ensures the order is never "anonymous" even before ERP mapping is finished.

 

 

Comments

The <Comments> element, when located within the ItemOut (or ItemDetail) block, is used to transmit specific notes or instructions related to a particular line item. Unlike header-level comments, these notes apply exclusively to the specific SKU or service on that line.

<Comments>For Mike</Comments>

 

Element Structure

The Comments element is a flexible container that typically holds plain text or, in some advanced configurations, references to external attachments.

XML Tag Description Business Context
<Comments> The parent container for item-level notes. Can include an xml:lang attribute (e.g., en-US).
Plain Text The actual note content. Instructions such as "Engrave with name" or "Must be delivered by Friday."
<Attachment> (Optional) A reference to an external file. Used if the community has attached a spec sheet or image to the specific item.

Common Use Cases

  • Special Instructions: "Please package in dry ice" or "Requires hazardous material handling."
  • Customization Details: Specific colors, sizes, or engraving text not captured in the part ID.
  • Service Details: Specific dates or times for on-site services.
  • Internal References: Cross-references to internal project notes.

 

 

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="">
                <Identity/>
            </Credential>
        </From>
        <To>
            <Credential domain="">
                <Identity/>
            </Credential>
        </To>
        <Sender>
            <Credential domain="">
                <Identity/>
                <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">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

When Unimarket sends an OrderRequest to a supplier's endpoint via an HTTP POST request, the receiving system is required to provide a synchronous acknowledgement. This acknowledgement confirms that the message was successfully received and is syntactically valid.

<?xml version="1.0" encoding="UTF-8"?>
<cXML>
    <Response>
        <Status code="200" text="OK">Purchase Order Processed Successfully</Status>
    </Response>
</cXML>

 

HTTP Status Code

The response must be returned with an HTTP 200 OK status code. This indicates that the server successfully processed the request.

cXML Response Structure

The body of the response must be a valid cXML document containing a <Response> element and a <Status> element.

Element / Attribute Value Description
<cXML> — The root element, containing standard attributes like payloadID and timestamp.
<Response> — The container for the response content.
<Status> — Defines the outcome of the request.
code 200 The cXML-specific success code (integer).
text OK or Success A short, human-readable description of the status.

 

 

Exchange Rates

In the Unimarket ecosystem, orders are transmitted using the currency defined by the Supplier's Store. To support the customer's internal accounting and budgetary requirements, Unimarket includes additional metadata to show the equivalent value in the Customer's Functional Currency.

 

Example of the OrderRequestHeader element containing 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>

 

Example of ItemOut element also shows the exchange: 

<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>

 

Header Level: The Exchange Rate Extrinsic

To provide a global conversion factor for the transaction, an <Extrinsic> element is included within the <OrderRequestHeader>.

Attribute Value Description
name ExchangeRate Identifies the conversion factor.
Value e.g., 1.625 The multiplier used to convert the functional currency to the transaction currency (or vice versa, depending on community config).

Extended Money Element Attributes

Unimarket extends the standard cXML <Money> element (used in UnitPrice, Total, Tax, and Shipping) with custom attributes. This ensures that every financial value carries its functional equivalent and the specific rate applied at the line level.

Money Element Attributes:
  • currency: The transaction currency (Supplier's currency).
  • alternateAmount: The value of the element in the Customer's functional currency.
  • alternateCurrency: The ISO currency code for the Customer's functional currency.
  • exchangeRate: The specific rate used for this calculation (included in UnitPrice and Shipping within ItemOut).

Note: More information on how exchange rates are managed is available on help article Exchange Rates.

 

 

Distributions

The <Distribution> element is located within the <ItemOut> block and allows the community to attach internal accounting codes (GL strings) to specific line items. While these codes are primarily for the community's internal financial tracking, they are included in the Purchase Order to provide transparency and assist with automated invoicing.

<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>

 

Element Structure and Hierarchy

A distribution defines how the cost of an item is allocated. In some configurations, a single item may be "split" across multiple accounts, leading to multiple distribution blocks.

XML Tag Description Business Context
<Distribution> The parent container for accounting data. Usually contains one or more <Accounting> blocks.
<Accounting> The container for the specific account string. Includes a name attribute identifying the accounting system (e.g., "ERP-Financials").
<AccountingSegment> A specific part of an account code. Represents segments like "Fund", "Department", or "Object Code".
<Charge> The monetary value allocated to this account. Useful when a line item is split across multiple funding sources.

Key Attributes

  • id: A unique identifier for the specific distribution within the item.
  • description: A human-readable label for the accounting segment (e.g., "Grant ID").

 

Example Distribution for an Item

A demonstration of 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

While standard <Distribution> elements provide the monetary charge for an account, Unimarket includes a specialized <Extrinsic> element within the <ItemDetail> block to provide a summary of the percentage-based allocations for a line item.

This is particularly useful for systems that require the "split" ratio (percentage) rather than just the final calculated currency amount.

<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>

 

Structure: The Distribution Container

The allocation data is encapsulated within a primary Extrinsic element.

Attribute Value Description
name unimarket-distribution-details The identifier for the distribution percentage summary.

Percentage Allocation Logic

Inside this container, Unimarket provides repeating details for each account code applied to the item. This ensures that even if an item's cost is split across 5 different departments, the percentage for each is explicitly stated.

  • Account Identifier: The specific GL string or account name.
  • Percentage: The portion of the item's total cost assigned to that account (e.g., 50.00 for 50%).

 

 

Common cXML Elements

The tables show some examples of where to find common fields used from the Header and Item levels.

 

Header Level Mapping Table

The following table details the attributes and elements used to define the overall Purchase Order.

Detail cXML Path (XPath)
Environment cXML/Request/@deploymentMode
Order Date cXML/Request/OrderRequest/OrderRequestHeader/@orderDate
Order Number cXML/Request/OrderRequest/OrderRequestHeader/@orderID
Order Status cXML/Request/OrderRequest/OrderRequestHeader/@type
Ship To ID cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/@addressID
Ship To Name cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/Name
Deliver To / Attn cXML/Request/OrderRequest/OrderRequestHeader/ShipTo/Address/PostalAddress/DeliverTo
Street (Lines 1-3) .../PostalAddress/Street[1]
City .../PostalAddress/City
State / Region .../PostalAddress/State
Post / ZIP Code .../PostalAddress/PostalCode
Country .../PostalAddress/Country
Buyer Name cXML/Request/OrderRequest/OrderRequestHeader/Contact[@role="buyer"]/Name
Buyer Email cXML/Request/OrderRequest/OrderRequestHeader/Contact[@role="buyer"]/Email
Order Total cXML/Request/OrderRequest/OrderRequestHeader/Total/Money
Shipping Total cXML/Request/OrderRequest/OrderRequestHeader/Shipping/Money
Tax Total cXML/Request/OrderRequest/OrderRequestHeader/Tax/Money
Order Note cXML/Request/OrderRequest/OrderRequestHeader/Extrinsic[@name="shippingNote"]

 

ItemOut (Item Level) Mapping Table

The following table describes the attributes and elements found within each repeated <ItemOut> block.

Note: The [*] notation indicates that the ItemOut element is a collection that repeats for every line item in the order.

Detail cXML Path (XPath) 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 / 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

 

 

What's Next Related