Order Integration cXML Specifications

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.

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.

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

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> include alternateCurrency and alternateAmount attributes 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 with name="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 code attribute must be in the 200 range (other codes are considered errors).

6. Common cXML Elements Mapping

Header Level

Item Level