cXML PunchOut Carts

PunchOutOrderMessage

The cXML PunchOutOrderMessage document contains the shopping cart items the shopper checked out from the eCommerce site. It is possible that the document will not contain any items if the shopper is returning from the eCommerce site with an empty cart.

Cart Transmission

The PunchOutOrderMessage must be sent back to the eProcurement system from the shoppers web browser. Upon submitting the cart via an HTML form, the user will return to the eProcurement system and no longer be on the suppliers site.

The HTML below consists of a form that is automatically submitted via JavaScript. Typically when clicking the "Checkout" button on the eCommerce site, users are redirected to a page with a loading message and the HTML <form>.

The example HTML below contains 2 variables that must be replaced with HTML escaped values:
buyer_form_post_url - the BuyerFormPost/URL from the PunchOutSetupRequest
xml - the cXML PunchOutOrderMessage document

<form id="cxml_form" method="POST" action="{{buyer_form_post_url}}" enctype="application/x-www-form-urlencoded">
  <input type="hidden" name="cXML-urlencoded" value="{{xml}}">
</form>
<script type="text/javascript">document.getElementById('cxml_form').submit()</script>

Credentials

The Header element is typically ignored by eProcurement applications when processing PunchOutOrderMessage documents. Instead, the BuyerCookie can be used to identify the user/session that was used to PunchOut.

BuyerCookie

The BuyerCookie element should contain the same value that was in the BuyerCookie element in the PunchOutSetupRequest for the current user.

eProcurement applications should not use the BuyerCookie as a method of authenticating users upon returning from the PunchOut site. The information in the BuyerCookie element will be exposed to the supplier and could be used by a bad actor to gain unauthorized access to the eProcurement system. Browser cookies should be used for tracking the user’s session and authenticating the user upon return. An appropriate use case for the BuyerCookie is to include unique identifiers for the vendor and current user. These can be used to determine which vendor to assign the shopping cart items to and to determine which user’s shopping cart/requisition the items should be added to in the event that their session has expired. If their session has expired, the items should be added to their active cart/requisition and the user should be required to re-authenticate (login).

PunchOutOrderMessageHeader

The PunchOutOrderMessageHeader element contains an operationAllowed attribute that should be set to "create" unless Edit/Inspect functionality is supported by the ecommerce site. The element should also contain a Total element with the sum of the cart items, shipping, and tax. Tax and Shipping elements can optionally be included if these amounts are known at the time the cart is sent back to the e-procurement system.

<PunchOutOrderMessageHeader operationAllowed="create">
  <Total>
    <Money currency="USD">33.43</Money>
  </Total>
  <Shipping>
    <Money currency="USD">4.50</Money>
    <Description xml:lang="en-US">USPS</Description>
  </Shipping>
  <Tax>
    <Money currency="USD">1.34</Money>
    <Description xml:lang="en-US">Sales Tax</Description>
  </Tax>
</PunchOutOrderMessageHeader>

ItemIn elements

Each PunchOutOrderMessage/ItemIn element represents a single item in the users shopping cart.

XPath Description Required

[@quantity]

Item quantity

Yes

ItemID/SupplierPartID

Supplier part number or SKU for the item. This should be a unique identifier for the product.

Yes

ItemID/SupplierPartAuxiliaryID

Internal supplier ID for cart item

No

ItemDetail/UnitPrice

Unit price of item

Yes

ItemDetail/Description

Description of the item

Yes

ItemDetail/UnitOfMeasure

Unit of Measure

Yes

ItemDetail/Classification

Commodity code or product classification

Sometimes

ItemDetail/ManufacturerName

Manufacturer

No

ItemDetail/ManufacturerPartID

Manufacturer Part Number

No

ItemDetail/Extrinsic[name="ImageURL"]

Product image URL

No

ItemID/SupplierPartAuxiliaryID

The SupplierPartAuxiliaryID field can be used to associate a value with the item that is included with any cXML orders generated from the cart. The field is not usually visible to the end user in their eProcurement system. This field can be used to reference the original shopping cart/session.

ItemDetail/UnitOfMeasure

The Unit of Measure (UOM) is the marketed units by which an item will be delivered when purchased and to which the unit price refers. Unit prices should be in reference to 1 UOM. Some e-procurement systems require the code to be one of a pre-defined list of UOM’s.

Example ItemIn

<ItemIn quantity="1">
  <ItemID>
    <SupplierPartID>300925</SupplierPartID>
    <SupplierPartAuxiliaryID>275451934678936</SupplierPartAuxiliaryID>
  </ItemID>
  <ItemDetail>
    <UnitPrice>
      <Money currency="USD">22.43</Money>
    </UnitPrice>
    <Description xml:lang="en">Swingline 747 Stapler</Description>
    <UnitOfMeasure>EA</UnitOfMeasure>
    <Classification domain="UNSPSC">44121615</Classification>
    <ManufacturerPartID>747</ManufacturerPartID>
    <ManufacturerName>Swingline</ManufacturerName>
    <Extrinsic name="ImageURL">https://s3.amazonaws.com/equallevelcdn/images/misc/swingline-747-rio-red.jpg</Extrinsic>
  </ItemDetail>
</ItemIn>

Share